CP/M® 




SYMBOLIC INSTRUCTION 
DEBUGGER 

USER'S GUIDE 



SID™ 

Symbolic Instruction Debugger 
User's Guide 



Copyright © 1978 and .1981 

Digital Research 
P.O. Box 579 
160 Central Avenue 
Pacific Grove, CA 93950 
(408) 649-3896 
TWX 910 360-5001 



All Rights Reserved 



COPYRIGHT 



I' 



Copyright © 1978 and 1981 by Digital Research. All 
rights reserved. No part of this publication may be 
reproduced, transmitted, transcribed, stored in a 
retrieval system, or translated into any language or 
computer language, in any form or by any means, 
electronic, mechanical, magnetic, optical, chemical, 
manual or otherwise, without the prior written 
permission of Digital Research, Post Of f ice Box 579, 
Pacific Grove, California, 93950 . 

This manual is, however, tutorial in nature. Thus, 
the reader is granted permission to include the 
example programs, either in whole or in part, in his 
own programs. 



DISCLAIMER 

Digital Research makes no representations or 
warranties with respect to the contents hereof and 
specifically disclaims any implied warranties of 
merchantability or fitness for any particular 
purpose. Further, Digital Research reserves the 
right to revise this publication and to make changes 
from time to time in the content hereof without 
obligation of Digital Research to notify any person 
of such revision or changes. 



TRADEMARKS 

CP/M is a registered trademark of Digital Research. 
ASM, DDT, MAC and SID are trademarks of Digital 
Research. Intel is a registered trademark of Intel 
Corporation. 



The "SID User's Guide" 
Digital Research TEX Text 
the United States of 
Press/Monterey. 



was prepared using the 
Formatter and printed in 
America by Commercial 



************************************ 

* Fourth Printing: January 1982 * 
************************************ 



Foreword 



SID, TM ' the CP/M® symbolic debugger, expands upon the features 
of the CP/M standard debugger described in the "CP/M Dynamic 
Debugging Tool (DDT) User's Guide" and provides greatly enhanced 
facilities for assembly level program checkout. Specifically, SID 
includes real-time breakpoints, fully monitored execution, symbolic 
disassembly, assembly, and memory display ' and fill functions. 
Further, SID operates with "utilities" that can be dynamically 
loaded with SID to provide traceback and histogram facilities. 

Section 1 of this manual describes the command forms that 
initiate SID and the command lines that direct the actions of the 
SID program. Section 2 describes SID's ability to reference 
absolute machine addresses through symbolic expressions. Section 3 
describes the commands that direct the debugging process. The SID 
utilities, described in Section 4, provide additional debugging 
facilities. Section 5 contains several examples of SID debugging 
sessions. 
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Section 1 
SID Operation Under CP/M 



1.1 Starting SID 

Type one of the following commands to start the SID program. 

(a) SID 

(b) SID x.y 

(c) SID x.HEX 

(d) SID x.UTL 

(e) SID x.y u.v 

(f) SID * u.v 

In each case, SID loads into the Transient Program Area (TPA) and 
relocates itself to the top of the TPA, overlaying the Console 
Command Processor portion of CP/M. Figure 1-1 shows memory 
organization before SID is loaded while Figure 1-2 shows the memory 
configuration after SID is loaded and relocated. Due to the 
relocation process, SID is independent of the exact memory size that 
CP/M manages in a particular computer configuration. 



(High Memory) 




TPA 



(Low Memory) 



JMP BDOS 



Figure 1-1. Memory Configuration Before SID Loads 



All Information Presented Here is Proprietary to Digital Research 



SID User's Guide 



1.1 Starting SID 



BDOS 



SID 
JMP BDOS 



TPA 



JMP SID 



Figure 1-2. Memory Configuration After SID Loads 

After loading and relocating, SID alters the BDOS entry address 
to reflect the reduced memory size, as shown in Figure 1-2, and 
frees the lower portion of the TPA for use by the program under 
test. Note that although SID occupies only 6K of upper memory when 
operating, the self-relocation process necessitates a minimum 20K 
CP/M system for initial setup, leaving about 10K for the test 
program. 

Command form (a) above loads and executes SID without loading a t 
test program into the TPA. Use this form to examine memory or write 1 
and test simple programs using the built-in assembly features of 
SID. 

Form (b) above is similar to (a) except that the file given by 
x.y is automatically loaded for subsequent test. Note that although 
x.y is loaded into the TPA, it is not executed until SID passes 
program control to the program under test using one of the following 
commands: C (Call) , G (Go) , T (Trace) , or U (Untrace) . It is your 
responsibility to ensure that there is enough space in the TPA to 
hold the test program as well as the debugger. If the program x.y 
does not exist on the diskette or cannot be loaded, SID issues the 
standard "?" error response. If no load error occurs, SID responds 1 
as follows: 

NEXT PC END 
nnnn pppp eeee 

where nnnn, pppp, and eeee are hexadecimal values that indicate the 
next free address following the loaded program, the initial value of 
the program counter, and the logical end of the TPA, respectively. 
Thus, nnnn is normally the beginning of the data area of the program 
under test; PPPP is the starting program counter (set to the 
beginning of the TPA) , and eeee is the last memory location 
available to the test program, as shown in Figure 1-3. Although x.y , 
usually contains machine code, the operator can name an ASCII file, 
in which case these program addresses are less meaningful. 
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1.1 Starting SID 



BDOS 



SID 
JMP BDOS 

eeee: (Free Space) 
nnnn : 

(Test 
pppp: program) 



JMP SID 



Figure 1-3. Memory Configuration After Test Program Load 



Command form (c) is similar to form (b) except that the test 
program is assumed to be in Intel "hex" format, as directly produced 
by ASM or MAC. In this case, the initial value of the program 
counter is obtained from the terminating record of the hex file 
unless this value is zero, in which case the program counter is set 
to the beginning of the TPA. As the ASM and MAC manuals discuss, 
the program counter value can be given on the "END" statement in the 
source program. Again, it is your responsibility to ensure that the 
hex records do not overlay portions of the SID debugger or CP/M 
Operating System. If the hex file does not exist or if errors occur 
in the hex format, SID issues the "?" response. Otherwise, the 
principle program locations shown in the previous paragraph are 
listed at the console. 

Use command form (d) when a SID utility function is to be 
included. In this case, SID is first loaded and relocated as above. 
The utility function is then loaded into the TPA. Utility functions 
are also self-relocating and immediately move to the top of the TPA, 
placing themselves directly below the SID program. The BDOS entry 
address is changed to reflect the reduced TPA, as shown in Figure 1- 
4. Generally, the utility program prints sign-on information and 
may or may not prompt for input from the console. Exact details of 
utility operation are given in Section 4 , "SID Utilities." 
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1.1 Starting SID 



BDOS 


SID 




UTL 


JMP 


BDOS 


TPA 


JMP 


UTL 



Figure 1-4. Memory Configuration Following Utility Load 



Command form (e) is similar to (c) , except that the symbol 
table given by u.v is loaded with the program x.y. Symbol 
information is loaded from the current top of the TPA downward 
toward the program under test, as shown in Figure 1-5. 



BDOS 



SID 



(UTL If 
Present) 



SYMBOLS 
JMP BDOS 



Free Space 



Test Program 



JMP SYMBOLS 



Figure 1-5. Memory Configuration Following Symbol Load 

The symbol table is in the format produced by the CP/M Macro 
Assembler. In particular, the symbol table must be a sequence of 
address and symbol name pairs, where the address consists of four 
hexadecimal digits, separated by a space from the symbol that takes 
on this address value. The symbol consists of up to 15 graphic 
ASCII characters terminated by one or more tabs (fl) or a carriage- 
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1.1 Starting SID 



return line-feed sequence. Note that you can create or alter a 
symbol table using the CP/M editor, as long as this format is 
followed. 

The response following program load is as shown in command form 
(b) above, giving essential program locations. When SID begins 
symbol load, it displays the following message: 

SYMBOLS 

This message indicates that any subsequent error is due to the 
symbol load process. In particular, the "?" error following the 
SYMBOLS response is due to a non-existent or incorrectly formatted 
symbol file. 

Command form (f) is similar to (e) , except that no program is 
loaded with the symbol file u.v. 

Examples of typical commands that start the SID program are 
shown below. 



(a) 


SID 


(b) 


SID 


(b) 


SID 


(c) 


SID 


(c) 


SID 


(d) 


SID 


(d) 


SID 


(e) 


SID 


(e) 


SID 


(e) 


SID 


(f) 


SID 



DUMP.COM 
DUMP .ASM 
SAMPLE. HEX 
DUMP .HEX 
TRACE. UTL 
HIST.UTL 

DUMP.COM DUMP.SYM 
DUMP. HEX DUMP.SYM 
TEST.COM TEST.ZOT 
* DUMP.SYM 



1.2 SID Command Input 

Command input to SID consists of a series of "command lines" 
that direct the actions of the SID program. These commands allow 
display of memory and CPU registers, and direct the execution and 
breakpoint operations during test program debugging. 

When SID is ready to accept the next command, it displays a "#" 
at the console. Each command is based upon a single letter, 
followed by optional parameters, and terminated by a carriage 
return. Note that all standard line editing features of CP/M are 
available, with a maximum of 64 command characters. The following 
table lists the CP/M line editing functions. 
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■Pa hi D 


x x. \~tr / n LaXiic EiU i 1 1 fly tontioib 


Control 


Function 


Character 




Tc 


CP/M system reboot, return to CCP 


TE 


Physical end-of-line 


Th 


Delete last character and backspace 




c ur so r 


Tp 


Print console output (on/off toggle) 


TR 


Retype current input line 


Is 


Stop/start console output 


Tu 


Delete current input line 


Tx 


(Same as TU) 


r ubout 


Delete and echo last character 



The T character indicates that you must simultaneously hold down the 
control key while depressing the particular function key. Note that 
the TR, TU, and TX keys cause CP/M to type a "#" at the end of the 
line to indicate that the line is being discarded. ( 

I 

Various SID commands produce long typeouts at the console (see 
the "D" command which displays memory, for example) . In this case, 
you can abort the typeout before it completes by typing any key at 
the console (a "return" suffices). 

The single letter commands that direct the actions of SID are 
typed at the beginning of the command line. You can enter commands 
in upper- or lower-case. Table 1-2 summarizes the valid commands. 
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1.2 SID Command Input 



Table 1-2. Command Letters 



Letter 


Meaning 


7V 
ft 


Abociuijxe aiiec tiy to memory 


n 


Call to memory location from SID 


n 


Hi en 1 p \7 • TTlom^ K \t in Kov anH 7A CP T T 
uiopiay HiciituLy in iicx cuiu ftov^ii 


r 


riii memory with constant value 


G 


Go to test program for execution 


H 


Hexadecimal arithmetic 


I 


Input CCP command line 


L 


List 8080 mnemonic instructions 


M 


Move memorv block 


P 


Pass point set, reset, and display 


R 


Read test program and symbol table 


S 


Set memory to data values 


T 


Trace test program execution 


U 


Untrace (monitor) test program 


X 


Examine state of CPU registers 



Although the details of each of the commands are given in later 
sections, nearly all of the commands accept parameters following the 
letter that governs the command actions. The parameters can be 
counters or memory addresses, and can appear in both literal and 
symbolic form, but eventually reduce to values in the range 0-65535 
(four hexadecimal digits) . 

As an example, the "display memory" command can take the 
following form: 

Dssss , eeee 

where D is the command letter, and ssss and eeee are "command 
parameters" that give the starting and ending addresses for the 
display, respectively. In their simplest form, ssss and eeee can be 
literal hexadecimal values, as shown below. 

D100 ,300 

These values instruct SID to print the hexadecimal and ASCII values 
contained in memory locations 0100H through 300H. 

Although you can usually refer to program listings to obtain 
absolute machine addresses, SID supports more comprehensive 
mechanisms for quick access to machine addresses through program 
symbols. In particular, the command parameters can consist of 
"symbolic expressions" which are described fully in the following 
sec t ion. 
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Section 2 
SID Symbolic Expressions 



An important facility of SID is the ability to reference 
absolute machine addresses through symbolic expressions. Symbolic 
expressions can involve names obtained from the program under test 
that are included in the "SYM" file produced by the CP/M Macro 
Assembler. Symbolic expressions can also consist of literal values 
in hexadecimal, decimal, or ASCII character string form. These 
values can then be combined with various operators to provide access 
to subscripted and indirectly addressed data or program areas. This 
section describes symbolic expressions so that you can incorporate 
them as command parameters in the individual command forms that 
follow this section. 



2.1 Literal Hexadecimal Numbers 

SID normally accepts and displays values in hexadecimal. The 
valid hexadecimal digits consist of the decimal digits through 9 
along with the hexadecimal digits A, B, C, D, E, and F, 
corresponding to the decimal values 10 through 15, respectively. 

A literal hexadecimal number in SID consists of one or more 
contiguous hexadecimal digits. If you type four digits, then the 
leftmost digit is most significant, while the rightmost digit is 
least significant. If the number contains more than four digits, 
the rightmost four are taken as significant, and the remaining 
leftmost digits are discarded. The examples below show the 
corresponding hexadecimal and decimal values for the given input 
values. 



INPUT VALUE HEXADECIMAL DECIMAL 

1 0001 1 

100 0100 256 

fffe FFFE 65534 

10000 0000 

38001 8001 32769 



2.2 Literal Decimal Numbers 

Although SID's normal number base is hexadecimal, you can 
override this base on input by preceding the number with a "#" 
symbol, which indicates that the following number is in the decimal 
base. In this case, the number that follows must consist of one or 
more decimal digits (0 through 9) with the most significant digit on 
the left and the least significant digit on the right. Decimal 
values are padded or truncated according to the rules of hexadecimal 
numbers, as described above, by converting the decimal number to the 
equivalent hexadecimal value. 
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2.2 Literal Decimal Numbers 



The input values shown to the left below produce the internal 
hexadecimal values shown to the right below: 



2.3 Literal Character Values 

As an operator convenience, SID also accepts one or more 
graphic ASCII characters enclosed in string apostrophes (') as 
literal values in expressions. Characters remain as typed within 
the paired apostrophes (i.e., no case translation occurs) with the 
leftmost character treated as the most significant, and the 
rightmost character treated as least significant. Similar to 
hexadecimal numbers, character strings of length one are padded on 
the left with zero, while strings of length greater than two are 
truncated to the rightmost two characters, discarding the leftmost 
remaining characters. 

Note that the enclosing apostrophes are not included in the 
character string, nor are they included in the character count, with 
one exception. To include the possibility of writing strings that 
include apostrophes, a pair of contiguous apostrophes is reduced to 
a single apostrophe and included in the string as a normal graphic 
character. 

The strings shown to the left below produce the hexadecimal 
values shown to the right below. (For these examples, note that 
upper-case ASCII alphabetics begin at the encoded hexadecimal value 
41, lower-case alphabetics begin at 61, a space is hexadecimal 20, 
and an apostrophe is encoded as hexadecimal 27). 



INPUT VALUE 



HEXADECIMAL VALUE 



#9 
#10 
#256 
#65535 
#65545 



0009 
000A 
0100 
FFFF 
0009 



INPUT STRING 



HEXADECIMAL VALUE 



'AB' 
'ABC' 
'aA' 



0041 
4142 
4243 
6141 
0027 
27 27 
2041 
4120 



' A' 
'A ' 
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2.4 Symbolic References 

Given that a symbol table is present during a SID debugging 
session, you can reference values associated with symbols through 
the following three forms of a symbol reference: 

(a) .s 

(b) @s 

(c) =s 

where s represents a sequence of one to fifteen characters that 
match a symbol in the table. 

Form (a) produces the address value (i.e., the value associated 
with the symbol in the table) corresponding to the symbol s. Form 
(b) produces the 16-bit "word" value contained in the two memory 
locations given by .s, while form (c) results in the 8-bit "byte" 
value at . s in memory. Suppose, for example, that the input symbol 
table contains two symbols, and appears as follows: 

0100 GAMMA 010 2 DELTA 

Further, suppose that memory starting at 0100 f^ntains the following 
byte data values: 

0100: 02 
0101: 3E 
010 2: 4D 
0103: 22 

Based upon this symbol table and these memory values, the 
symbol references shown to the left below produce the hexadecimal 
values shown to the right below. Recall that 16-bit 8080 memory 
values are stored with the least significant byte first, and thus 
the word values at 0100 and 0102 are 3E02 and 224D, respectively. 



SYMBOL REFERENCE HEXADECIMAL VALUE 

.GAMMA 0100 

. DELTA 10 2 

@ GAMMA 3E02 

@ DELTA 224D 

= GAMMA 000 2 

=DELTA 004D 



2.5 Qualified Symbols 

Note that duplicate symbols can occur in the symbol table due 
to separately assembled or compiled modules that independently use 
the same name for differing subroutines or data areas. Further, 
block structured languages, such as PL/M, allow nested name 
definitions that are identical, but non-conflicting. Thus, SID 
allows reference to "qualified symbols" that take the form: 
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2.5 Qualified Symbols 



S1/S2/ . . . /Sn 

where SI through Sn represent symbols that are present in the table 
during a particular session. 

SID always searches the symbol table from the first to last 
symbol, in the order the symbols appear in the symbol file. For a 
qualified symbol, SID begins by matching the first SI symbol, then 
scans for a match with symbol S2, continuing until symbol Sn is 
matched. If this search and match procedure is not successful, SID 
prints the "?" response to the console. Suppose, for example, that 
the symbol table appears as follows: 

0100 A 0300 B 0200 A 3E00 C 20F0 A 0102 A 

in the symbol file, with memory initialized as shown in the previous 
section. The unqualified and qualified symbol references shown to 
the left below produce the hexadecimal values shown to the right 
below. 



SYMBOL REFERENCE HEXADECIMAL VALUE 

.A 0100 

@A 3E02 

.A/A 0200 

.C/A/A 0102 

=C/A/A 00 4D 

@B/A/A 20F0 



2.6 Symbolic Operators 

Literal numbers, strings, and symbol references can be combined 
into symbolic expressions using unary and binary "+" and "-" 
operators. The entire sequence of numbers, symbols, and operators 
must be written without embedded blanks. Further, the sequence is 
evaluated from left to r ight, . producing a four digit hexadecimal 
value at each step in the evaluation. Overflow and underflow are 
both ignored as the evaluation proceeds. The final value becomes 
the command parameter, whose interpretation depends upon the 
particular command letter that precedes it. 

When placed between two operands, the "+" indicates addition of 
the second operand to the previously accumulated value. The sum 
becomes the new accumulated value to this point in the evaluation. 
If the expression begins with a unary "+", then the immediately 
preceding (completed) symbolic expression is taken as the initial 
accumulated value (zero is assumed at SID startup). For example, 
the command : 

DFE00+#128 ,+5 

contains the first expression "FEO0+#128" which adds FE00 and 
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2.6 Symbolic Operators 



(decimal) 128 to produce FE80 as the starting value for this display 
command. The second expression "+5" begins with a unary "+" which 
indicates that the previous expression value (FE80) is to be used as 
the base for this symbolic expression, producing the value FE85 for 
the end of the display operation. Thus, the command given above is 
equivalent to: 

DFE80,FE85 

The "-" symbol causes SID to subtract the literal number or 
symbol reference from the 16-bit value accumulated thus far in the 
symbolic expression. If the expression begins with a minus sign, 
then the initial accumulated value is taken as zero. That is, 

-x is computed as 0-x 

where x is any valid symbolic expression. For example, the 
following command: 

DFF00-200 ,-#512 

is equivalent to the simple command: 

DFDOO ,FE00 

A special up-arrow operator, denoted by ,,/s " , denotes the top- 
of-stack in the program under test. In general, a sequence of n up- 
arrow operators extracts the nth stacked item in the test program, 
but does not change the test program stack content or stack pointer. 
This particular operator is used most often in conjunction with the 
G (Go) command to set a breakpoint at a return from a subroutine 
during test, and is described fully under the G command. 



2.7 Sample Symbolic Expressions 

The formulation of SID symbolic expressions is most often 
closely related to the program structures in the program under test. 
Suppose you want to debug a sorting program that contains the data 
items listed below: 



LIST: names the base of a table of byte values to 

sort, assuming there are no more than 255 
elements, denoted by LIST(O), LIST(l), ... , 
LIST (254) . 

N: is a byte variable which gives the actual 

number of items in LIST, where the value of N 
is less than 256. The items to sort are stored 
in LIST(O) through LIST(N-l). 
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2.7 Sample Symbolic Expressions 



I: is the byte subscript which indicates the next 

item to compare in the sorting process. That 
is, LIST(I) is the next item to place in 
sequence, where I is in the range through N- 
1. 

Given these data areas, the command 

D.LIST,+#254 
displays the entire area reserved for sorting: 

LIST(O), LIST(l), . . . , LIST(254) 
The command 

D.LIST,+=I 

displays the LIST vector up to and including the next item to sort: 

LIST(O), LIST(l), . . . , LIST(I) 
The command 

D.LIST+=I ,+0 
displays only LIST(I). Finally, the command 

D.LIST,+=N-1 

displays only the area of LIST that holds active items to sort: 

LIST(O), LIST(l), . . . , LIST(N-l) 

The exact manner in which SID uses symbolic expressions 
depends upon the individual command that you issue. The following 
section details these commands. 
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SID Commands 



Enter SID commands at the console following the "#" prompt. 
The commands direct the debugging process by allowing alteration and 
display of CPU registers and memory as well as the controlling 
execution of the program under test. 

The following sections describe the commands that SID accepts. 



3.1 The Assemble (A) Command 

The A command allows you to insert 8 08 machine code and 
operands into the current memory image using standard Intel 
mnemonics, along with symbolic references to operands. The A 
command takes the forms: 



where s represents any valid symbolic expression. Form (a) begins 
inline assembly at the address given by s, where each successive 
address is displayed until you type a null line (i.e., a single 
carriage return). Form (b) is equivalent to (a), except the 
starting address for the assembly is taken from the last assembled, 
listed, or traced address (see the "L" , "T" , and "U" commands). The 
following command sequence, for example, assembles a short program 
into the Transient Program Area (note that you must terminate each 
command line with a carriage return) : 



As each successive address is prompted, you can either enter a 
mnemonic instruction or return to SID command mode by entering a 
single carriage return (a single " . " is also accepted to terminate 
inline assembly to be consistent with the "S" command) . 

Delimiter characters that are acceptable between mnemonic and 
operand fields include space or tab sequences. 

Invalid mnemonics or ill-formed operand fields produce "?" 
errors. In this case, control returns back to command mode, where 
you can proceed with another command line, or simply return to 
assembly mode by typing a single "A", since the assumed starting 
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(a) As 

(b) A 

(c) -A 



A100 

0100 MVI A, 10 
010 2 DCR A 
0103 JNZ 102 
0106 RST 7 
0107 



begin assembly at 0100 
load A with hex 10 
decrement A register 
loop until zero 
return to debugger 
single carriage return 
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3.1 The Assemble (A) Command 



address is automatically taken from the last assembled address. 

The assembler/disassembler portion of SID is a separate module, 
and can be removed to increase the available debugging space. Thus, 
form (c) is entered to remove the module, returning approximately 1 
1/2 K bytes. Since the entire SID debugger requires approximately 6 
K bytes, this reduces SID requirements to ab'out 4 1/2 K bytes. When 
the assembler/disassembler module is removed in this manner, the A 
and L commands are effectively removed. Further, the trace and 
untrace functions display only the hexadecimal codes, and the 
traceback utility displays only hexadecimal addresses. Any existing 
symbol information is also discarded at this point, although such 
information can be reloaded (see the "I" and "R" commands). 

Examples of valid assemble commands are shown below: 

A100 

A#100 

A.CRLF+5 

A@GAMMA+@X-=I 

A+30 

Given that the command A100 has been entered, the following 
interaction could take place between SID and the operator: 



A, B, and SOURCE are symbols that appear in the symbol table. In 
this case, SID computes the address difference between A and B as 
the operand for the MVI instruction. The LXI H operand becomes the 
address of SOURCE, while the LXI D instruction receives the operand 
value .SOURCE+100 because .SOURCE was the immediately preceeding 
symbolic expression value. This particular program segment moves a 
block of memory determined by the address values of the 
corresponding symbols. 
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OPERATOR INPUT 



0100 
010 2 
0105 
0108 
0109 
010A 
010B 
010C 
010D 
0110 



MVI C, .A-.B 

LXI H,. SOURCE 
LXI D, + 100 
MOV A,M 
INX H 
STAX D 
INX D 
DCR C 
JNZ 108 

("return" only) 
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3.2 The Call (C) Command 

The C command performs a call to an absolute location in 
memory, without disturbing the register state of the program under 
test. The C Command takes the forms: 

(a) Cs 

(b) Cs f b 

(c) Cs,b f d 

Although the C command is designed for use with SID utilities, it 
can call on test program subroutines to perform program 
initialization, or to make CP/M BDOS calls that initialize various 
system parameters before executing the test program. 

Form (a) above performs a call on absolute location s, where s 
is a symbolic expression. In this case, registers BC = 0000 and DE 
= 0000 in the call. Normal exit from the subroutine is through 
execution of a RET instruction that returns control to SID, followed 
by the normal SID prompt. 

Form (b) above is equivalent to (a), except that the BC 
register pair is set to the value of expression b, while DE is set 
to 0000 . 

Form (c) is similar to ( b) ; the BC register pair is set to the 
value b while the DE pair is set to the value of d. Several 
examples of valid C commands are shown below. Refer also to the SID 
utility discussion for examples of the C command in utility 
initialization, data collection, and display functions. 

C100 

C#4096 

CD I SPLAY 

C@JMPVEC+=X 

C.CRLF,# 34 

C.CRLF,@X,+=X 



3.3 The Display Memory (D) Command 

The D command displays selected segments of memory in both byte 
(8-bit) and word (16-bit) formats. The display appears in both 
hexadecimal and ASCII form in the output. The D command takes the 
following forms: 



(a) 


DS 


(b) 


DS, f 


(c) 


D 


(d) 


D,f 


(e) 


DWs 


(f) 


DWs, f 


(g) 


DW 


(h) 


DW,f 
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Forms (a) through (d) display memory in byte format, while 

forms (e) through (h) display memory in word format. The byte 
format display appears as: 

aaaa bb bb bb . . . bb cc . . . cc 

where aaaa is the base address of the display line and the sequence 
of (up to) 16 bb pairs represents the hexadecimal values of the data 
stored starting at address aaaa. The sequence of c's represent the 
same data area displayed in ASCII format, where possible. A period 
(.) is displayed as a place holder when the data item does not 
correspond to a graphic character. 

Byte mode displays are "normalized" to address boundaries that 
are multiples of 16. That is, if the starting address aaaa is not a 
multiple of 16, then the display line is printed to the next 
boundary address that is a multiple of 16. Each display line that 
follows contains 16 data elements until the last display line is 
enc ountered. 

Command forms (e) through (h) display in word mode which is 
similar to the byte mode display described above, except that the 
data elements are printed in a double byte format: 

aaaa wwww wwww . . . wwww cc . . . cc 

where aaaa is the starting address for the display line and the 
sequence of (up to 8) wwww's represent the data items that are 
stored in memory beginning at aaaa. Similar to the byte mode 
display, the sequence of c's represent the decoded ASCII characters 
starting at address aaaa. As in the byte mode display, a period is 
displayed as a place holder when the character in that position is 
non-graphic. 

Contrary to the byte mode display, address normalization to 
modulo 16 address boundaries does not occur in the word mode 
display. Recall that 8080 double words are stored with the least 
significant byte first, and thus the word mode display reverses each 
byte pair so that the individual data items are displayed as four 
digit hexadecimal numbers with the most significant digits in the 
high-order positions. 

Command form (a) displays memory in byte format starting at 
location s for 1/2 of a standard CRT screen (12 lines) . This form 
of the command is useful when you want to view a segment of memory 
beginning at a particular position with an indefinite ending 
address. 

Command form (b) is similar to (a) , but specifies a particular 
ending address. In this case, the start address is taken as s with 
the display continuing through address f . Recall that you can abort 
excessively long typeouts by depressing any keyboard character, such 
as a carriage return. 
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Form (c) is similar to (a) and (b) , except the starting address 
for the display is taken from the last displayed address, or from 
the value of the memory address registers (HL) in the case that no 
previous display has occurred since the last breakpoint. It is 
often convenient, for example, to use form (a) to display a segment 
of memory, followed by a sequence of D commands of form (c) to 
continue the display. Each D command displays another 1/2 screen of 
memory. 

Command form (d) is similar to (b) except the starting address 
is taken automatically as described in form (c) above. 

Assume, for example, that decimal values 1 through 255 are 
stored in memory starting at hexadecimal address 0100. The command: 

D100,12A 

produces the expanded form of the display shown below: 

0100 01 02 03 04 (etc.) 0E OF 10 .. (etc.) .. 
0110 11 12 13 14 (etc.) IE IF 20 .. (etc.) . 
0120 21 22 23 24 (etc.) 29 2A 2B !"#$%&'()* + 

Command forms (e) through (h) parallel the byte display formats 
given by (a) through (d) , except that the display is given in word 
format. Form (e) displays in word format from location s for 1/2 
screen, while form (f) displays from location s through location f. 
Form (g) displays from the last display location, or from HL if 
there has been an immediately preceding breakpoint with no 
intervening display. Form (h) is similar to (g) , but displays 
through location f. The command: 

DW100,128 

for example, produces the expanded form of the following output 
lines: 

0100 0201 0403 (etc.) 0E0D 100F .. (etc.) .. 
0110 1211 1413 (etc.) 1E1D 201F .. (etc.) . 
0120 2221 2423 (etc.) 2928 2B2A !"#$%&'()* + 

The following are examples of valid D commands: 

DF3F 

D#100,#200 

D . GAMMA ,. DEL TA+# 30 

D. GAMMA 

DW@ALPHA,+#100 
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3.4 The Fill Memory (F) Command 

The F command fills memory with a constant byte value, and 
takes the form: 

Fs, f ,d 

where s is the starting address for the fill; f is the ending 
(inclusive) address for the fill, and d is the 8-bit data item to 
store in locations s through f. It is your responsibility to not 
fill memory locations that are occupied by the resident portions of 
CP/M, including areas reserved for SID. The following are examples 
of valid F commands: 

F100 ,3FF,FF 

F. GAMMA, + #100 ,#23 

F@ALPHA,+=I ,=X 



3.5 The Go (G) Command 

The G command passes program control to a program under test. 
Execution proceeds in real time from the address specified by the G 
command. That is, the G command releases processor control from SID 
to the program under test. Execution does not return to SID until a 
break or pass point is reached (see the "P" command for a discussion 
of pass points). The operator can force a return to SID, however, 
by interrupting the processor with a "restart 7" (RST 7) provided by 
the program under test, or forced by external hardware such as front 
panel control switches, if available. 

The G command takes the following forms: 



(a) 


G 


(b) 


Gp 


(c) 


G, a 


(d) 


Gp,a 


(e) 


G,a,b 


(f) 


Gp , a , b 


(g) 


-G 


(h) 


-Gp 


(i) 


-G, a 


(j) 


-Gp, a 


(k) 


-G , a , b 


(1) 


-G,p,a,b 



Forms (a) through (f) start test program execution with 
symbolic features enabled, while forms (g) through (1) are identical 
in function, but disable the symbolic features of SID. In 
particular, form (a) starts test program execution from the program 
counter (PC) given in the machine state of the program under test 
(see the "X" command for machine state display). In this case, no 
breakpoints are set in the test program. Form (b) is similar to 
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(a) , but initializes the test program's PC to p before starting 
execution. Again, no breakpoints are set in the test program. 
Similar to (a) , form (c) starts execution from the current value of 
PC but sets a breakpoint at location a. The test program receives 
control and runs in real time until the address a is encountered. 
Note that control returns to SID upon encountering a pass point or 
RST 7, as described above. 

Upon encountering the breakpoint address a, the break address 
is printed at the console in the form: 

*a . s 

where s is the first symbol in the table that matches address a, if 
it exists. Note that the temporary breakpoint at address a is 
automatically cleared when SID returns to command mode (see the "P" 
command for permanent breakpoints) . 

Form (d) combines the functions of (b) and (c) : the test 
program PC is set to the address p and a temporary breakpoint is set 
at location a. As above, the breakpoint is cleared when control 
returns to SID. It should be noted that an immediate breakpoint 
always occurs if p = a. If this is not desired, however, you can 
use the trace function to single step past the current address, 
followed by a G command (see the "T" command for actions of the 
trace facility) . 

Form (e) extends the breakpoint facility by allowing two 
temporary break addresses at a and b. Program execution begins at 
the current PC and continues until either address a or b is 
encountered. Both temporary break addresses are cleared when SID 
returns to command mode. Form (f) is similar to (e) , except the 
initial value of PC is set to location p before starting the test 
program. 

Note that the instruction at a breakpoint address is not 
executed when you use the G command. Suppose, for example, that a 
subroutine named TYPEOUT is located at address 0302 in a test 
program, consisting of the machine code: 

TYPEOUT: 

030 2 MOV E,A 
0303 MVI C,2 
0305 JMP 0005 

Suppose further that you are testing a program that makes calls on 
the TYPEOUT subroutine where a break address is to be set. Enter 
the command : 

G, .TYPEOUT 

Test program execution proceeds from the current PC value and stops 
when the TYPEOUT subroutine is reached, with the breakpoint message: 

*030 2 .TYPEOUT 
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indicating that control has returned from the test program to SID. 
At this point, the program counter of the test program is at 
location 0302 (i.e., .TYPEOUT) , and the instruction at this location 
has not yet been executed. You can execute through the TYPEOUT 
subroutine using any of the commands G, T, or U. The following is a 
useful command in this situation: 

6, A 

This command continues execution from 0302, and sets a breakpoint at 
the topmost stacked element (given by """). Since the topmost 
stacked element must be the subroutine return address, this 
particular G command executes the TYPEOUT subroutine, with a break 
upon return to the instruction following the original call to 
TYPEOUT . 

Command forms (g) through (1) correspond directly to functions 
(a) through (f) , except that pass points are not displayed until the 
corresponding pass counters reach 1 (see the "P" command for details 
of intermediate pass point display) . 

Note that the essential difference between the G command and 
the U (Untrace) command is that execution proceeds unmonitored in 
real time with the G command, while each instruction is executed in 
single-step mode with the U command. Fully monitored execution 
under the U command has the advantage that you can regain control at 
any point in the test program execution. However, execution time of 
the test program is seriously degraded in Untrace mode since 
automatic breakpoints are set and cleared following each 
instruction. 

The following are examples of valid G commands: 
G100 

G100 ,103 

G.CRLF, .PRINT, #1024 

G@JMPVEC+=I , .ENDC, .ERRC 

G, .ERRSUB 

G, .ERRSUB, +30 

-G100 ,+ 10 ,+ 10 



3.6 The Hexadecimal Value (H) Command 

The H command performs hexadecimal computations including 
number base conversion operations. The H command takes the 
following forms: 

(a) Ha,b 

(b) Ha 

(c) H 

Form (a) computes the hexadecimal sum and difference using the two 
operands, resulting in the display: 
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ssss dddd 

where ssss is the sum a+b, and dddd is the difference a-b, ignoring 
overflow and underflow conditions. 

Form (b) performs number and character conversion, where a is a 
symbolic expression. The display format in this case is: 

hhhh #ddddd *c' .s 

where hhhh is the four digit hexadecimal value of a; #ddddd is the 
(up to) five digit decimal value of a; c is the ASCII value of a 
when a is graphic, and s is the first symbol in the table which 
matches the value a, when such a symbol exists. Assume, for 
example, that the symbol GAMMA is located at address 0100, as in 
previous examples. The H commands shown to the left below result in 
the displays shown to the right below: 



COMMAND 



RESULTING DISPLAY 



H0,1 

H41 

H100 

H .GAMMA 

H=GAMMA 

H@GAMMA 

HFF+=GAMMA 

H'A' 

H'A'+=GAMMA 



0001 
0041 
0100 
0100 
0001 
0201 
0100 
0041 
0042 



FFFF 



#65 ' 
#256 
#256 
#1 

#513 
#256 
#65 ' 
#66 ' 



A' 

.GAMMA 
.GAMMA 



.GAMMA 
A' 



Command form (c) prints the complete list of symbols along with 
their corresponding address values. The list is printed from the 
first to last symbol loaded, and can be aborted during typeout by 
depressing any keyboard character. 

3.7 The Input Line (I) Command 

When testing programs that run in the CP/M environment, it is 
often useful to simulate the command line that the CCP normally 
prepares upon program load. The I command takes the form: 



Iccccc 



ccc 



where the sequence of c's represent ASCII characters that normally 
follow the test program name in the CCP command line. For example, 
the CP/M "DUMP" program is normally started in CCP command mode by 
typing : 

DUMP X.COM 

which causes the CCP to search for and load the DUMP.COM file, and 
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pass the filename "X.COM" as a parameter to the DUMP program. In 
particular, the CCP initializes two default file control blocks, 
along with a default command line that contains the characters 
following the DUMP command. 

To trace and debug a program such as DUMP, invoke the SID 
program with the following command: 

SID DUMP.COM 

which loads the command file containing the DUMP machine code. If 
the symbol table is available, the SID invocation is: 

SID DUMP.COM DUMP.SYM 

In either case, SID loads the DUMP program and prompts the console 
for a command. To simulate the CCP's command line preparation, type 
the command: 

IX.COM 

where the "I" denotes the Input command, which is followed by the 
simulated command line. The operator can then commence the debug 
run with default areas properly setup. 

The I command specifically initializes the default file control 
block in low memory, labelled DFCB1, that is normally located at 
005C. The file control block which is initialized by the I command 
is complete in the sense that the program can simply address DFCBl 
and perform and open, make, or delete operation without further 
initialization. As a convenience, a second filename is initialized 
at location DFCB2, which is at address DFCB1+0010 (hexadecimal). 

It is your responsibility to move the second drive number, 
filename, and filetype to another region of memory before performing 
file operations at DFCBl since the 16-byte region at DFCB2 is 
immediately overwritten by any file operation. Further, the default 
buffer, labelled DBUFF , is initialized to contain the entire command 
line with the first byte of the buffer containing the command line 
length. In a standard CP/M system, the DBUFF area is assumed to 
start at 0080 and end at OOFF. Note, however, that the I command 
restricts the simulated CCP command line to 6 3 characters since 
SID's line buffer is used in the simulation. 

Given an I command of the form: 

I dlrfl.tl d2:f2.tl 

where dl: and d2: are (optional) drive identifiers; fl and f2 are 
(up to eight character) filenames, and tl and t2 are (up to three 
character optional) filetypes, two default file control block names 
are prepared in the form: 
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DFCB1: dl' fl' tl' 00 00 00 00 
DFCB2: d2' f2' t2' 00 00 00 00 

00 (current record field) 

If dl: is empty in the original command line, then dl' = 00 (which 
automatically selects the default drive) , otherwise if dl = A, B, C, 
or D, then dl" = 01, 02, 03, or 04, respectively, which properly 
initializes the file control block for automatic disk selection. 
Field fl' is initialized to the ASCII filename given by f 1 , padded 
to an eight character field with ASCII blanks. Similarly, tl' is 
initialized to the ASCII f iletype, padded with blanks in a field of 
length three. 

Lower-case alphabetics in fl and tl are translated to upper- 
case in fl' and tl', respectively. Names that exceed their 
respective length fields are truncated on the right. Finally, the 
extent field is zeroed in preparation for a BDOS call to open or 
make the file. 

The second default file control block given by d2 , f 2 , and t2 
is prepared in a similar fashion and stored starting at location 
006C. Note that the current record field at location 007C is also 
initialized to 00. If any of the fields f 1 , tl , f 2 , and t2 are not 
included in the command line, their corresponding fields in the 
default file control blocks are filled with blanks. 

Ambiguous references that use the "*" or "?" characters are 
processed in the same manner as in the CCP: the "*" symbol in a 
name or type field causes the field to be right-filled with "?" 
characters. The input lines shown below illustrate the default area 
initialization which takes place for various unambiguous and 
ambiguous filenames. The areas shown to the right give the 
hexadecimal values which begin at the labelled addresses, where 
ASCII values A, B, C, and D have the hexadecimal values 41, 42 , 43, 
and 44, respectively. Further, the special characters " . " , 

"*", and "?" have the ASCII encoded values 3A , 2E , 2A , and 3F , while 
an ASCII space has the hexadecimal value 20: 



COMMAND LINE DEFAULT DATA AREA INITIALIZATION 



DFCB1: 


00 


















20 


20 


20 


20 


20 


20 


20 


20 




20 


20 


20 


00 


00 


00 


00 




DFCB2: 


00 


















20 


20 


20 


20 


20 


20 


20 


20 




20 


20 


20 


00 


00 


00 


00 






00 


















00 
















DBUFF: 


00 


00 
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UL JD _L • 


no 


















41 


z0 


20 


20 


20 


20 


20 


20 




42 


20 


20 


00 


00 


00 


00 




DFCB2: 


00 


















20 


20 


20 


20 


20 


20 


20 


20 




20 


20 


20 


00 


00 


00 


00 






00 


















00 
















DBUFF: 


04 


O A 

20 


41 


'"*T-l 

2E 


42 


00 






DFCB1: 


01 


















42 


20 


o a 

20 


20 


20 


20 


O A 

20 


O A 

20 




43 


20 


20 


00 


00 


00 


00 




DFCB2: 


02 


















44 


20 


20 


20 


20 


20 


20 


20 




A C 

4 5 


A A 

20 


20 


00 


00 


00 


A A 

00 






00 


















00 
















DBUFF: 


OB 


41 


3A 


42 


2E 


43 


20 








42 


3A 


44 


2E 


45 


00 





I AA*.B?C D: 



DFCB1: 


00 


















41 


41 


3F 


3F 


3F 


3F 


3F 


3F 




42 


3F 


43 


00 


00 


00 


00 




DFCB2: 


04 


















20 


20 


20 


20 


20 


20 


20 


20 




20 


20 


20 


00 


00 


00 


00 






00 


















00 
















DBUFF: 


0B 


20 


41 


41 


2A 


2E 


42 








3F 


43 


20 


44 


3A 


00 





Note that the I command is also used in conjunction with the R 
command to read program files and symbol tables after SID 
has initially loaded. Details of the use of I in 
this situation are given with the R command that follows. 

Additional valid I commands are given below: 

I x.dat 

Ix. inp y.out 

Ia:x.inp b:y.out $-p 

ITEST.COM 

I TEST. HEX TEST .SYM 
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3.8 The List Code (L) Command 

The L command disassembles machine code in the memory of the 
machine, with symbolic labels and operands placed in the appropriate 
fields, where possible. The L command takes the forms: 

(a) Ls 

(b) Ls,f 

(c) L 

(d) -Ls 

(e) -Ls,f 

(f) -L 

Form (a) lists disassembled machine code starting at symbolic 
location s for 1/2 CRT screen (12 lines) . Form ( b) specifies an 
exact range for disassembly: s specifies the starting location, and 
f gives the final disassembly location. Form (c) is similar to (a) , 
but disassembles from the last listed, assembled (see the A 
command) , traced (see the T and U commands) , or break address (see 
the G and P commands) . Since form (c) also lists 1/2 CRT screen, it 
is often used following form (a) to continue the disassembly process 
through another segment of the program. Forms (d) through (f) 
parallel (a) through (c) , but disable the symbolic features of SID. 
In particular, the minus prefix prevents any symbol lookup 
operations during the disassembly. 

The L command output takes the following form: 

sssss : 

aaaa opcode operand .ttttt 

where "sssss:" represent a symbol which labels the program location 
given by the hexadecimal address aaaa ? when the symbol exists. The 
"opcode" field gives the 8080 mnemonic for the instruction at 
location aaaa, and the "operand" field, when present, gives the 
hexadecimal values which follow the opcode in memory. The symbol 
".ttttt" is printed when the instruction references a memory address 
which matches a symbol in the table. 

When the operation code at the list address is not a valid 8080 
mnemonic, the output form is: 

??= hh 

where hh is the hexadecimal value of the invalid operation code. 
Several valid L commands are listed below. 
L100 

L#1024 ,#1034 
L.CRLF 
L@ICALL,+ 30 
-L.PRBUFF+=I ,+'A' 



All Information Presented Here is Proprietary to Digital Research 



SID User's Guide 



3.9 The Move Memory (M) Command 



3.9 The Move Memory (M) Command 

The M command allows you to move blocks of data values from one 
area of memory to another. The M command takes the form: 

Ms, h,d 

where s is the start address of the move operation; h is the high 
(last) address of the move, and d is the starting destination 
address to receive the data. SID transfers one byte at a time from 
the start address to the destination address. Each time a byte 
value is moved, the start and destination addresses are incremented 
by one. The move process terminates when the start address 
increments past the final f address. The command: 

M100 ,1FF ,3000 

for example, replicates the entire block of memory from 0100 through 
01FF at the destination area from 3000 through 30FF in memory. The 
data block from 0100 through 01FF remains intact. 

Note that data areas may overlap in the move process. The 
command: 

M100,1FF,101 

shows an instance where the value at location 0100 is propagated 
throughout the entire block from 0101 through 200. 

A number of valid M commands are listed below: 

M-100 ,FFD0,100 

M. X,+=Z , . Y 

M . GAMMA ,+FF , . DELTA 

M@ALPHA+=X , + # 50 ,+ 10 



3.10 The Pass Counter (P) Command 

The P command allows you to set and clear "pass points" and 
"pass counts" in the program under test. The P command takes the 
following forms: 

(a) Pp 

(b) Pp,c 

(c) P 

(d) -Pp 

(e) -P 

A "pass point" is a program location to monitor during 
execution of the test program. Similar to a temporary breakpoint 
(see the G command) , a pass point causes SID to stop execution of 
the test program each time an active pass point is reached. Unlike 
a temporary breakpoint, a pass point is not automatically cleared 
each time it is reached during execution. Further, unlike a 

All Information Presented Here is Proprietary to Digital Research 



SID User's Guide 



3.10 The Pass Counter (P) Command 



temporary breakpoint, a pass point break occurs after the 
instruction as the pass address is executed. In this way, you can 
simply continue the execution of the test program under control of a 
G command until the next pass point is executed, or until a 
temporary breakpoint is reached. 

Each pass point can have an optional "pass count" which 
defaults to the value 1. The pass count enhances this facility by 
allowing several passes through a pass point before the break 
actually occurs. In particular, a pass count in the range 1-FF 
(decimal 1 through 255) can be associated with a particular pass 
point. Each time the instruction at a pass point is executed, its 
corresponding pass count is decremented. The decrementing process 
proceeds until the pass count reaches 1, at which time the break 
address is printed and execution of the test program stops. When a 
pass count reaches 1, the pass point becomes a permanent break 
address which halts execution each time the instruction is executed. 
Note that a pass count does not change once it has reached 1. Up to 
eight distinct pass points can be actively set at any particular 
time. 

Form (a) sets a pass point at address p with a pass count of 1, 
causing address p to become a permanent breakpoint. Form (b) is 
similar, except that the pass count is initialized to c. Form (c) 
displays these active pass points in the format: 

cc pppp .sssss 

where cc is the hexadecimal value of the pass count that is 
currently associated with the pass address pppp, and sssss is a 
symbol that matches the address pppp, if such a symbol exists. 

Form (d) clears the pass point at address p, while form (e) 
clears all active pass points. Note that the command: 

PP,0 

is equivalent to form (d) . 

Each time a pass point is encountered, SID prints the pass 
information in the format: 

cc PASS pppp .sssss 

where cc is the current pass count at pass point pppp (cc is 
decremented when greater than 1). As above, the symbol sssss 
corresponding to address pppp is printed when possible. 

The special command forms "-G" and "-U" to disable the 
intermediate pass trace as the counters are decremented down to 1. 
Suppose, for example, the TYPEOUT subroutine is a part of a program 
under test, as shown in the G command above. Issue the command: 

P .TYPEOUT, #30 
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This P command sets a pass point at the location labelled by 
"TYPEOUT" which is assumed to exist in the symbol table. The pass 
count is set to decimal 30, which allows the pass point to execute 
30 times before a breakpoint is taken. Given that the pass point at 
TYPEOUT is in effect, the command: 

G 

starts execution of the test program with no temporary breakpoint. 
Each time the pass point is executed, the following pass trace is 
executed. 

IE PASS 0302 .TYPEOUT 

(register trace) 

ID PASS 030 2 .TYPEOUT 

(register trace) 

1C PASS 0302 .TYPEOUT 

(register trace) 

• • • 

01 PASS 0302 .TYPEOUT 
(register trace) 
*303 

The "register trace" shows the state of the CPU registers before the 
"MOV E,A" at TYPEOUT is executed (see the "X" command for register 
display format). Note that the final breakpoint address is 0303, 
which follows the "MOV" instruction at the pass address 302. 
Depress any keyboard character during the pass point trace, and SID 
immediately stops execution following the instruction at the pass 
point address. If the command 

-G 

had been issued, the intermediate pass traces do not appear at the 
console. In this particular case, only the final trace: 

01 PASS 030 2 .TYPEOUT 
(register trace) 
*303 

is printed. Although the intermediate pass traces are not 
displayed, you can abort execution by depressing a keyboard 
character. If an intermediate pass point is encountered with trace 
disabled, SID aborts execution and returns control to the keyboard. 

Temporary breakpoints can also be set while pass points are in 
effect. That is, commands such as: 

Ga, b 
Ga, b, c 
G,b 
G, b,c 

can be issued that intermix with the permanent breakpoints that are 
set with the P command. Note, however, that permanent breakpoints 
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override the temporary breakpoints that are given by b and c when 
they occur at the same address. Further, T and U command can trace 
sections of the test program while permanent breakpoints are in 
effect. In this case, the pass counts decrement as described above, 
with a break taken when the count reaches 1. 

Valid P commands are shown below: 

P100 ,FF 
P.BDOS 

P@ICALL+30,#20 
-P.CRLF 



3.11 The Read Code/Symbols (R) Command 

The R command, in conjunction with the I command, reads program 
segments, symbol tables, and utility functions into the Transient 
Program Area. The R command takes the forms: 

(a) R 

(b) Rd 

The I command sets the filenames that will be involved in the read 
operation. Form (a) reads the program and/or symbol table given by 
the I command without applying an offset to the load addresses. 
Form (b) adds the displacement value d to each program load address 
and/or symbol table address. Note that this addition takes place 
without overflow checks so that negative bias values can be applied. 
As a simple case, the usual initiation of SID: 

A>SID X.COM 

can be replaced by the following sequence of commands: 

SID Starts SID without a test program 

IX.COM Initialize the input line 

R Read the test program to memory 

The response from SID in this case is exactly the same as the normal 
initialization, with the "NEXT PC END" message as described in 
Section 1. 

A program and symbol file can be read by preceding the R 
command with an I command of the form: 

I x.y u.v 

where x.y is the program to load, and u.v is the symbol table file. 
Note that y is usually the type "COM" ; x is usually the same as u, 
and v is usually the type "SYM". Thus, the following is a typical 
command sequence of this form: 

IDUMP.COM DUMP. SYM 
R 
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This sequence reads the DUMP.COM program file into the Transient 
Program Area and loads the symbol table with the information given 
by DUMP.SYM. Programs with file type "HEX" load into the locations 
specified in the Intel formatted hexadecimal records, while programs 
with filetype "UTL" are assumed to be SID utility functions that 
load and relocate automatically. All other filetypes are assumed 
absolute, and load starting at the base of the transient area. 
Utility functions automatically remove any existing symbol 
information when they relocate, but in all other cases the symbol 
load operations are cumulative. In particular, the special input 
form: 

I* u.v 

R 



skips the program load since there is an asterisk in the program 
name position, and loads only the symbol table file. Thus, a 
sequence of commands of the above form can load the symbol tables 
for selective portions of a large program that was initially 
developed in small modules. 

Suppose, for example, that a report generation program has been 
developed using MAC, which consists of the following modules: 

IOMOD.ASM I/O Module 

SORT .ASM File Sorting Module 

MERGE .ASM File Merge Module 

FORMAT .ASM Report Format Module 

MAIN .ASM Main Program Module 

DATA .ASM Common Data Definitions 



Suppose further that each module has been separately assembled using 
MAC, resulting in several "HEX" and "SYM" files corresponding to the 
individual program segments. The program segments have been brought 
together using SID to form a memory image by typing the sequence of 
commands: 



SID 

IIOMOD.HEX 
R 

I SORT. HEX 
R 

I MERGE .HEX 
R 

I FORMAT. HEX 
R 

IMAIN .HEX 
R 

IDATA .HEX 
R 



Start the SID program 
Initialize IOMOD 
Read I/O Module 
Initialize SORT 
Read Sort Module 
Initialize MERGE 
Read Merge Module 
Initialize FORMAT 
Read Format Module 
Initialize MAIN 
Read Main Module 
Initialize DATA Area 
Read Initialized Data 



Following this sequence, the Transient Program Area contains the 
complete memory image of the report generation program. Suppose the 
information printed following the last R command is: 
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NEXT PC END 
1B3E 0100 8E00 

which indicates that the high memory address is 1B3E. Using the H 
command : 

H1B 

you find that IB (hexadecimal) pages is the same as 27 (decimal) 
pages. At this point, return to CCP mode by typing either a 
control-C (warm start) , or "GO" command, which leaves the memory 
image intact. Then issue the command: 

SAVE 27 REPORT.COM 

to create a memory image file on the diskette. Then re-enter SID 
using the following command: 

SID REPORT.COM 

to load the entire module for testing. Individual portions of the 
report generator can then be symbolically accessed by selectively 
loading symbol tables from the original modules. For example, the 
MAIN and SORT modules can be debugged by subsequently loading the 
corresponding symbol information: 

I* MAIN .SYM 
R 

I* SORT. SYM 
R 

which prepares the symbol information for subsequent debugging. 
Individual segments of the report generator are then tested and 
reassembled. If an error is found in the SORT module, for example, 
the SORT. ASM file is edited to make necessary changes, and the 
module is reassembled with MAC, resulting in new "HEX" and "SYM" 
files for the SORT module only. Given that enough "expansion" area 
has been provided following the SORT module, SID is reinitiated and 
the SORT module is included: 

SID REP0RT.COM 

I SORT. HEX SORT. SYM 

R 

which overlays the changed SORT module in the original report 
generator memory image. You can then load additional symbol tables 
by typing I and R commands such as: 

I* MAIN. SYM 
R 

I* DATA. SYM 
R 

to access symbols in the SORT, MAIN, and DATA modules. 
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Note that several symbol table files can be concatenated using 
the PIP program (see the "CP/M Features and Facilities" manual for 
PIP operation) before SID is invoked. For example, the PIP command: 

PIP NOBUGS.SYM=IOMOD.SYM, SORT. SYM, MERGE. SYM, FORMAT. SYM 

creates a file called NOBUGS.SYM that holds the symbols for IOMOD, 
SORT, MERGE, and FORMAT. The SID command: 

SID REP0RT.COM NOBUGS.SYM 

loads the memory image for the report generator, along with the 
symbol tables for these particular modules. Additional symbol files 
can then be selectively loaded using I and R commands. The symbol 
file for the entire memory image can then be constructed using the 
PIP command: 

PIP REPORT . S YM=NOBUGS .SYM, MAI N . S YM , DATA .SYM 
which allows you to type: 

SID REP0RT.COM REPORT. SYM 

to load the memory image for the report generator, along with the 
entire symbol table. Recall, however, that the symbol table is 
always searched in load-order, and thus symbol names which are the 
same in two modules must be distinguished using qualified symbolic 
names (see Section 1). 

As mentioned above, form (b) allows a displacement value d to 
be added to each program address and symbol value. The displacement 
value has no effect, however, when the program is a SID utility 
(filetype "UTL"). The commands: 

IDUMP.HEX DUMP. SYM 
R1000 

for example, cause the DUMP program to be loaded 1000 (hexadecimal) 
locations above its normal origin, with properly adjusted symbol 
addresses. Note that the bias value can be any symbolic expression, 
and thus the command: 

R-200 

first produces a (two's complement) negative number which is added 
to each address. Since overflow from a 16-bit counter is ignored, 
this R command loads the program 200 (hexadecimal) locations below 
the normal load address, with symbol addresses biased by this same 
amount. 

Error reporting during the R command is limited to the standard 
"?" response, which indicates that either the program or symbol file 
does not exist, or the program or symbol file is improperly formed. 
Similar to the SID startup messages, the response 
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SYMBOLS 

occurs following program load, and appears before the symbol load. 
Thus, a "?" error before the SYMBOLS response indicates that the 
error occurred during the program load, while the "?" error after 
the SYMBOLS message indicates that an error occurred during the 
symbol file load operation. The exact position of a symbol file 
error can be found by subsequently using the H command to view the 
portion of the symbol table that was actually loaded. 



3.12 The Set Memory (S) Command 

The S command allows you to enter data into main memory. The 
forms of the S command are: 

(a) Ss 

(b) SWs 

Form (a) allows data to be entered at location s in byte (8-bit) or 
character string mode, while form (b) stores word (16-bit) mode data 
items. In either case, the SID program prompts the console with 
successive addresses, starting at location s, along with the data 
item presently located at that address. As each line prompt occurs, 
you can type a single carriage return or a symbolic expression 
(followed by a carriage return) , which is evaluated and becomes the 
new data item at that location. If you type a single carriage 
return, then the data element at that location remains unchanged. 
The S command terminates whenever an invalid data item is detected, 
or when you type a single " . " followed by a carriage return. Form 
(a) allows single byte data, and produces the standard "?" when a 
double byte value is entered with a non-zero high-order byte. In 
addition, form (a) also allows long ASCII string data to be entered 
in the format: 

"ccccc . . .ccccc 

where the sequence of c's (terminated with a carriage return) 
represents graphic ASCII characters to be entered at the prompted 
location. No translation from lower- to upper-case takes place 
during entry. Further, the next prompted address is automatically 
set to the first unfilled location following the input string. 

A valid input sequence following the command: 

S100 

is shown below, where the SID prompt is given on the left, and the 
operator's input lines are shown to the right, where "cr" denotes 
the carriage return key. 
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SID PROMPT 



OPERATOR INPUT 



0100 
0101 
0102 
0103 
0108 
0109 
010A 



C3 
24 
CF 
4B 
6E 
E2 
D4 



34cr 

#254cr 

cr 

"ASCIIcr 
=X+5cr 
'%'cr 
.cr 



A valid double byte input sequence following the command 
SW.X+#30 
is shown below: 



SID PROMPT 



2300 
2302 
2304 
2306 
2308 



006D 
4F32 
33E2 
FF11 
348F 



OPERATOR INPUT 

44Fcr 

@GAMMAcr 

cr 

.X+=I-#20cr 
.cr 



3.13 The Trace Mode (T) Command 

The T command allows you to single or multiple step a test 
program while viewing the CPU registers as they change. In 
addition, you can use the T command with SID utilities to collect 
test program data for later display (see the section entitled "SID 



Utilities") . 


The 


forms 


of the 


T 


command 


(a) 


Tn 










(b) 


T 










(c) 


Tn, c 










(d) 


T ,c 










(e) 


-T 


(with 


options 


a 


- d) 


(f) 


TW 


(with 


options 


a 


- d) 


(g) 


-TW 


(with 


options 


a- 


- d) 



Form (a) traces program execution from the current value of the 
program counter PC (see the "X" command for PC value as well as the 
format of the CPU state display). Form (b) is the trivial case of 
(a) with an assumed single step count of n = 1. In either case, the 
SID program displays the register state, along with the decoded 
instruction (assuming "-A" is not in effect) before each instruction 
is executed. For example, the command: 

T4 

traces four program steps, producing the format: 
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(register state 1) opcode 1 
label: 

(register state 2) opcode 2 
label: 

(register state 3) opcode 3 
label: 

(register state 4) opcode 4 *bbbb 



showing the register state before each corresponding operation code 
is executed. Each operation code is written in the same format as 
the L and X commands, with interspersed symbolic operands decoded 
wherever possible. In addition, instructions that reference memory, 
such as INR M, are listed with the memory operand in the form: 

opcode M =hh 

where "opcode" is the memory referencing instruction, and hh is the 
hexadecimal value contained in the memory address given by the HL 
register pair before the operation takes place. The interspersed 
labels show program addresses when they occur in the flow of 
execution. The final break address, denoted by "*bbbb" above, shows 
the value of the program counter after opcode 4 is executed. You 
can display the CPU state at this point by typing the single 
character "X" command. 

Forms (c) and (d) are used only with the SID utilities, and 
automatically perform a CALL c after each instruction executes. The 
value of c corresponds to a utility entry address for data 
collection. The following sections detail these forms. Note, 
however, that form (d) is equivalent to (c) with a single step count 
of n = 1. 

Forms given by (e) parallel (a) through (d) , but the preceding 
minus sign disables the symbolic features of SID. In particular, 
neither the symbolic operands nor the symbolic labels are decoded in 
the trace process. This option speeds up the operation of SID 
slightly in trace mode when large symbol tables are present. 

Forms given by (f) parallel (a) through (d) , but perform a 
"trace without call" function. It is often useful, for example, to 
trace mainline program code, but not trace into the subroutines 
which are called from the mainline execution. The TW command 
performs this function by running the test program in real time 
whenever a subroutine is entered, returning to fully traced mode 
upon return to the current subroutine level. If a return operation 
takes place at the current level (i.e., a RET is executed in fully 
traced mode) , then tracing continues at the encompassing subroutine 
or mainline program level. For example, suppose the mainline and 
subroutine structure shown below exists in a particular program: 



All Information Presented Here is Proprietary to Digital Research 



SID User's Guide 



3.13 The Trace Mode (T) Command 



MAINLINE SUBROUTINE 1 SUBROUTINE 2 ... SUBROUTINE n 



CALL SI 
MOV B,C 
MOV C , D 



SI: MOV A,C S2: MOV A,D 



CALL S2 
MOV C,E 
MOV D,E 



CALL S3 
MOV D,H 



Sn: MOV A,L 



MOV C,L 
MOV D f L 



JMP 0000 



RET 



RET 



RET 



Suppose further that the test program is stopped within subroutine 
SI before the call to subroutine S2. The command: 

T#100 

traces from SI through S2, S3, and so forth until level Sn is 
encountered. Although this form of the trace could be useful, it is 
often more enlightening to trace only at a particular subroutine 
level, and view the effects of the subroutine levels above SI. In 
this manner, an offending subroutine is often easily discovered 
without tracing non-essential program flows. If you type the 
following command while at subroutine level SI, all subsequent 
levels from S2 and beyond are executed in real time as if a "G" 
command had been performed at each CALL within SI. 

TW#100 

Upon executing the RET instruction within SI, tracing resumes at the 
mainline level. Any subroutine calls following CALL SI at the main 
level are not subsequently traced. 

Forms given by (g) parallel (a) through (d) , but disable the 
symbolic features of SID in the same manner as form (e) . 

Note that SID allows tracing up to Read Only Memory (ROM) 
program code. At the point ROM is entered, SID stops the trace 
operation, and runs the ROM code in real time. An automatic 
breakpoint is set which intercepts program control when ROM code is 
exited. The assumption, however, is that ROM code was entered via a 
subroutine call (CALL or RST n) , not via a PCHL or JMP instruction. 
In any case, the return address following the ROM execution is taken 
as the topmost address in the test program's stack. 

Note further that SID does not trace execution of calls through 
the BDOS code, since these operations are often quite lengthy, and 
can occassionally require real time operation to perform various 
disk functions. Thus, entry to the BDOS is intercepted by SID, and 
resumed following completion of the BDOS function. 

Abort tracing at any time by depressing a keyboard character. 
Do not use the RST instruction to terminate trace functions. 
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Valid trace commands are shown below: 
T100 

T# 30,. COLLECT 
-TW=I ,3E03 

3.14 The Untrace Node (U) Command 

The U command is similar to the T command given above, except 
that the CPU register state is not displayed at each step. Instead, 
the test program runs fully monitored so that program execution can 
be aborted at any time, or for the collection of data for a SID 
utility function. The forms of the U command parallel the T 
command : 



(a) 


Un 










(b) 


U 










(c) 


Un, c 










(d) 


U,c 










(e) 


-U 


(with 


options 


a 


- d) 


(f) 


UW 


(with 


options 


a 


- d) 


(g) 


-UW 


(with 


options 


a 


- d) 



Forms (a) through (d) perform the analogous functions of the "T" 
command forms (a) through (d) , without displaying the register state 
at each step. Forms given by (e) differ from the T command; 
however, instead of disabling the symbolic features, the following 
command forms: 

-Un 
-U 

-Un,c 
-U,c 

disable the intermediate pass point display (see the "P" command) , 
until the corresponding pass counts reach 1. 

Forms given by (f) correspond to the "T" command exactly, 
except that the trace display is disabled. In this case, the 
current subroutine level is run fully monitored, but higher 
subroutine levels run in real time. 

Forms given by (g) are similar to (f) , but disable the pass 
point display, as described above. 

You can abort execution in untrace mode by depressing any 
keyboard character. The break address is displayed, and control 
returns to SID command mode. 

Valid U commands are given below: 

UFFFF 

U#10000 , .COLLECT 
UW=GAMMA , . COLLECT 
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3.15 The Examine CPU State (X) Command 

The X command allows you to examine and alter the CPU state of 
the program under test. The X command takes the following forms: 

(a) X 

(b) Xf 

(c) Xr 

Form (a) displays the entire CPU state in the format: 

CZMEI A=aa B=bbbb D=dddd H=hhhh S=ssss P=pppp op sym 

where C, Z, M, E, and I represent the true or false conditions of 
the CPU carry, zero, minus, even parity, and interdigit carry, 
respectively. If the position contains a "-" then the corresponding 
flag is false, otherwise the flag letter is printed. The byte value 
aa is the value of the A register, while the double byte values 
bbbb, dddd, hhhh, ssss, and pppp, give the 16-bit values of the BC, 
DE, HL, Stack Pointer, and Program Counter, respectively. The field 
marked "op" gives the decoded mnemonic instruction at location pppp, 
unless "-A" is in effect, in which case the hexadecimal value of the 
operation code is printed. The "sym" field contains a decoded 
operand, when possible. Refer to the L command for the format of 
the symbolic instruction decoding. The single letter "X" command 
might result in a display of the form: 

C-M— A=03 B=34EF D=2000 H=334E S=4323 P=0100 LDA 0223 .Q 

which, for example, indicates that the carry and minus flags are 
true, while the zero, even parity, and interdigit carry flags are 
false. Further, the A register contains 03, while the B, C, D, E, 
H, and L registers contain the hexadecimal values 34, EF, 20, 00, 
33, and 4E , respectively. The value of the Stack Pointer is 4323, 
and the Program Counter is at location 0100. The next instruction 
to execute at location 0100 is an accumulator load (LDA) from 
location 233 . Further, the first symbol in the table that matches 
address 233 is Q. 

Form (b) allows you to change the state of the CPU flags. In 
this case, f must be one of the condition code letters: C, Z, M, E, 
or I. The present state of the flag is displayed (either the flag 
letter if true, or a "-" if false) . You can either type a single 
carriage return, which leaves the flag in its present state, or you 
can type a 1 to set the flag true, or a to reset the flag to 
false. Given that the carry flag is true, for example, the command: 

XC 

produces the SID response: 
C 

followed by a space, indicating that the carry is currently set, 
awaiting possible change. Enter a carriage return to leave the flag 
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set, or a to reset the carry to false. Similarly, if the zero 
flag is false, the command: 



XZ 



produces the SID response: 



indicating that the zero flag is false. Enter a carriage return if 
the state is to remain unchanged, or a 1 to set the zero flag to 
true. 



Form (c) allows alteration of the individual CPU registers, 
where r is one of the register names A , B , D , H , S , or P . In this 
case, the current content of the register is displayed, and the 
console is prompted for input. If you type a single carriage 
return, the data value remains unchanged. Otherwise, the symbolic 
expression is evaluated and becomes the new value of the register. 
Only byte values are acceptable when the "XA" form is used, while 
double byte values are accepted in the remaining forms. Note that 
the BC, DE , and HL registers must be altered as a pair. The SID 
interaction shown below is typical when the A register is altered: 



XA 

A=03 45 cr 



where you type the "XA" ; SID prints the "03" as the value of the A, 
register, and you type "45" as a replacement for A's value. The 
"cr" represents the carriage return key in this example and in the 
examples that follow. The following interactions with SID provide 
additional examples in the format described above: 



XB 

B=34EF cr (data remains unchanged) 
XD 

D=2000 2300 cr (D changes to 23) 
XH 

H=33 4E .GAMMA cr 
XS 

S = 4323 @STKPTR+#100 cr 
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Section 4 
SID Utilities 



SID utilities are special programs that operate with SID to 
provide additional debugging facilities. As described in Section 1, 
you load a SID utility by typing: 

SID x.UTL 

where x is the name of a utility program, described in the following 
sections. Upon initiation, the utility program loads, relocates, 
and prompts the console for any necessary parameters. Then you 
collect the necessary program test data (using the U or T command) , 
and display the information using a call to the utility display 
subroutine. The mechanisms for system initialization, data 
collection, and data display are given in detail below. 



4.1 Utility Operation 

A particular SID utility loads into memory in much the same 
manner as a normal test program. The utilities, however, 
automatically move themselves into high memory, occupying the region 
directly below the SID program, as described in Section 1. The 
utility load operation can be accomplished by simply typing the 
utility name with the SID command as shown above. You can also load 
a utility during the SID execution, as described in the I and R 
commands. Recall, however, that all existing symbol information is 
removed when the utility loads, and must be reinitialized if 
required for the debugging run. 

Normally, a SID utility has three primary entry points: 
INITIAL for utility (re) initialization, COLLECT for data collection, 
and DISPLAY for data display. After loading, the utility sets up 
these symbols in the table, and types the entry point addresses in 
the format: 



where iiii, cccc, and dddd are the hexadecimal addresses of the 
three entry points. Note, however, that the three symbolic names 
are equivalent to these three addresses. 

Following initial sign on, the utility may prompt the console 
for additional debugging parameters. After the interaction is 
complete, you can use the I and R commands to load test programs and 
symbol tables to proceed with the debug session. 



• INITIAL 
.COLLECT 
.DISPLAY 



cccc 
dddd 



mi 
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During the debug run, data collection takes place by running 
the test program in monitored mode using the U or T commands. 
Either of the following commands: 

UFFFF , .COLLECT 
UFFFF ,CCCC 

direct the SID program to run the test program from the current 
Program Counter for a maximum of 65535 (FFFF hexadecimal) steps, 
with a call to the data collection entry point of the utility 
program. Each instruction breakpoint sends information to the 
utility program, where it is tabulated for later display. Note that 
in this particular case, you can stop the untrace mode by depressing 
the return key before the sequence of 65535 steps is completed. 

Following a series of data collection operations, enter either 
of the following commands that call the utility DISPLAY entry point 
to print the accumulated data: 

C. DISPLAY 
Cdddd 

Then, resume the data collection process, as described above, 
followed by additional display operations. 

At any point, you can reinitialize the utility by typing either 
of the following commands: 

C INITIAL 
Ciiii 



which causes reinitialization of 
then prompts for additional 
reinitialization process. 



the utility tables. The utility 
parameters to complete the 



Note that loading and executing more than one utility function 
during a debugging session can produce unpredictable results. 

The remaining sections present the functions of the SID 
utilit ies. 

4.2 The HIST Utility 

The HIST utility creates a histogram (bar graph) of the 
relative frequency of execution in selected program segments of a 
program under test. The HIST utility allows you to monitor "hot 
spots" in the test program where the program is executing most 
frequently. 

After initial sign-on, as described in the previous section, 
the HIST utility prompts the input console: 



TYPE HISTOGRAM BOUNDS 
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You must respond with two symbolic expressions, separated by a 
comma : 

1111, hhhh 

where 1111 is the lowest address to monitor, and hhhh is the highest 
address. To collect histogram information, you must use one of the 
following command forms: 

Tn,c T,c TWn,c TW,c -Tn,c -T,c -TWn,c -TW,c 
Un,c U,c UWn,c UW,c -Un,c -U,c -UWn,c -UW,c 

where c is either . COLLECT , or the address corresponding to the 
COLLECT entry point. Although any of these commands may be used, 
the form: 

Un , . COLLECT 

is nearly always used since the trace output is disabled, the test 
program is fully monitored, and data collection takes place at each 
program step. 

Following a series of data collection operations, display the 
histogram by typing: 

C. DISPLAY or Cdddd 

The histogram is then printed in the following format: 

HISTOGRAM: 

ADDR RELATIVE FREQUENCY, MAXIMUM VALUE = mmmm 

aaaa ***** 
bbbb ******* 

cccc ********* 

*********** 

******************************************* 
****** 

where addresses aaaa through zzzz span the range from the low to 
high address range given in the initialization of HIST. The maximum 
value mmmm is the largest number of instructions accumulated at any 
of the displayed addresses, and the asterisks represent the bar 
graph of relative instruction frequencies, scaled according to the 
maximum value mmmm. The address range is automatically scaled over 
64 different address slots (aaaa, bbbb, ... ,zzzz, above), with a 
maximum of 6 4 asterisks in any particular bar of the graph. 

Given the above display, the "hot spot" is around the address 
range xxxx to zzzz. In this case, type either of the following 
commands to reinitialize the HIST utility: 

C. INITIAL 
Ciiii 



xxxx 

yyyy 

zzzz 
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Then the HIST initialization prompt and response follow, as shown 
below. 

TYPE HISTOGRAM BOUNDS xxxx,zzzz 
You can then rerun the test program using the command: 
UFFFF , .COLLECT 

After leaving enough time for the test program to reach "steady 
state," interrupt program execution by typing a return during the 
monitored execution. The display function is then reinvoked to 
expand the region between xxxx and zzzz, resulting in a more refined 
view of the frequently executed region. 

The L command can subsequently determine the exact instructions 
that are most frequently executed. If possible, the sequence of 
instructions can be somewhat improved, with an overall improvement 
in program performance. 



4.3 The TRACE Utility 

The TRACE utility obtains a backtrace of the instructions that 
led to a particular break address in a program under test. For 
example, a program might have an error condition that arises from a 
sequence of instructions that are difficult to find under normal 
testing. In this case, TRACE can collect program addresses as the 
test program executes, and display these addresses and instructions 
in most recent to least recent order when you request. To invoke 
SID with the TRACE utility, enter the following command: 

SID TRACE. UTL 

The utility responds as follows: 

INITIAL = iiii 
COLLECT = cccc 
DISPLAY = dddd 

In this case, the TRACE utility also prints the message: 
READY FOR SYMBOLIC BACKTRACE 

which indicates that the assembler/disassembler portion of SID is 
present, and will disassemble instructions when the backtrace is 
requested . 

You can then proceed to load a test program with optional 
symbol table. For example, you can load the DUMP program, by typing 
the command: 

IDUMP.COM DUMP.SYM 
R 
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The usual response: 

"NEXT PC END" 

indicates that the test program is loaded. At this point, the SID 
debugger is executing in high memory, along with the TRACE utility 
and the test program symbols. The test program is present in low 
memory, ready for execution. 

To obtain the simplest backtrace, type one of the U or T 
command forms shown with the HIST utility. In particular, a U 
command of the form: 



U# 500,. COLLECT 



executes 500 (decimal) program steps, and then automatically stops 
program execution. Type the following command to obtain a backtrace 
to the stop address: 



C. DISPLAY 



This command causes TRACE to display the label, address, and 
mnemonic information in the form: 



label-255: 

addr-255 opcode-255 sym-255 
label-254: 

addr-254 opcode-254 sym-254 
label-253: 

addr-253 opcode-253 sym-253 

label-000: 

addr-000 opcode-000 sym-000 



where label-255 down through label-000 represent the decoded 
symbolic labels corresponding to addresses given by addr-255 down 
through addr-000, when the symbolic labels exist. Opcode-255 down 
through opcode-000 represent the mnemonic operation codes 
corresponding to the backtraced addresses, and sym-255 down through 
sym-000 denote the symbolic operands corresponding to the operation 
codes, when the symbols exist. The operation codes are displayed in 
the same format as the list command. Note that in this display, the 
most recently executed instruction is at location addr-255, while 
the least recently executed instruction is at location addr-000. 
TRACE accounts for up to 256 instructions, which accumulate in T or 
U mode. The accumulated instructions are not affected by the 
DISPLAY function, but are cleared by the following call to 
reinitialize: 



C. INITIAL 



Full benefit of the TRACE utility requires concurrent use of 
TRACE with pass points (see the "P" command) . In particular, pass 
points are first set at program locations that are of interest in 
the backtrace. The program is then run to an intermediate location 
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where the test begins. At this intermediate test point, use the U 
command to execute the test program in fully monitored mode, with 
data collection at the COLLECT entry point of TRACE. Upon 
encountering one of the pass points in U mode, program execution 
breaks, and you regain control in SID command mode. The DISPLAY 
function of TRACE is then invoked to obtain the required backtrace 
information. 

As an example of this process, suppose the DUMP program is in 
memory with the TRACE utility, as shown above. Suppose further that 
you want to view the actions of the DUMP program on the first call 
to BDOS (i.e., the first call from DUMP to the CP/M Basic Disk 
Operating System, through location 0005). Assuming the symbol table 
is loaded, type the command: 

P .BDOS 

which sets a pass point at the BDOS entry, with corresponding pass 
count = 1. Then execute DUMP in monitored mode, collecting data at 
each instruction: 

UPPPF,. COLLECT 

The untrace count of FFFF (65535) instructions is, of course, too 
many in this case, but the assumption is that the DUMP program stops 
at the BDOS call before the instruction count is exceeded (if it 
does not, depress any keyboard character to force a program break) . 
In this case, the DUMP program executes only a few instructions 
before the BDOS call, resulting in the break information: 

01 PASS 000 5 .BDOS 

-ZEI A=80 B=0014 D=005C H=0000 S=0249 P=0005 JMP CCDF 
*CCDF 

showing the pass count 1, pass address 0005, symbolic location BDOS, 
register state, and break address. Since execution to this point 
was monitored and data was collected, invoke the TRACE function: 

C. DISPLAY 

which results in the display: 

BDOS: 



0005 


JMP 


CCDF 


01CA 


CALL 


0005 .BDOS 


01C8 


MVI 


C,0F 


01C5 


LXI 


D,005C .FCB 


01C2 


STA 


007C . FCBCR 


SETUP: 






01C1 


XRA 


A 


010A 


CALL 


01C1 .SETUP 


0107 


LXI 


SP,0257 .STKTOP 


0104 


SHLD 


0215 .OLDSP 


0103 


DAD 


SP 


0100 


LXI 


H,0000 
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Note that in this particular case, only 11 instructions were 
executed before the BDOS call, and thus the full 256 instruction 
capacity had not been exceeded. In fact, the backtrace shown above 
gives the complete history of the DUMP execution, from the first 
instruction at address 0100. You can then proceed to execute the 
DUMP program further by simply typing: 

UFFFF , .COLLECT 

with a break at the following call on BDOS. Given that the program 
execution is to stop on the 20th call on BDOS, type the pass 
command : 



P. BDOS, #20 



to set the pass count at 20 (decimal) . Enter the command: 



UFFFF, .COLLECT 



if intermediate passes are to be traced. Alternatively, type the 
command: 



-UFFFF , . COLLECT 



to disable intermediate traces. In either case, execution stops at 
the 20th BDOS call, and you can enter the display command: 



C. DISPLAY 



to view the trace to this particular BDOS call. 

Abort long typeouts by typing any keyboard character during the 
display. The ctl-S key freezes the display during output. Finally, 
recall that you can issue "C. DISPLAY" any number of times to 
reproduce the backtrace since the command does not clear the TRACE 
buffer. 

You can also use the TRACE utility when the disassembler module 
is not present. In this case, the instruction addresses are listed 
in the trace, while the mnemonics are not included. For example, 
the sequence of commands shown below loads the TRACE utility without 
the disassembler module, followed by the DUMP program without its 
symbol table : 

SID Load the SID Program 

-A Remove the Disassembler 

I TRACE .UTL Ready the TRACE Utility 

R Read the TRACE Utility 

IDUMP.COM Load the DUMP Program 

In this case, the TRACE utility prints the following sign-on 
message: 



"-A" IN EFFECT, ADDRESS BACKTRACE 
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e backtrace information is subsequently displayed in the format: 

addr-255 addr-254 addr-253 . . . addr-248 

addr-247 addr-246 addr-245 . . . addr-240 

• • • 

addr-007 addr-006 addr-005 . . . addr-000 
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This section contains several examples of SID debugging 
sessions. The examples are based upon a "bubble sort" of a byte 
value list. The bubble sort program is first listed in its 
undebugged form. A series of test, edit, and reassembly processes 
are shown which result in a final debugged program. In each case, 
the operator interaction with CP/M, ED, MAC, or SID is shown in 
normal type, while comments on each of the processes are given 
alongside in italics. 

The dialogue that follows contains the following sequence of 
operations: 



(1) 


TYPE SORT.PRN 




(2) 


TYPE SORT.SYM 




(3) 


TYPE SORT .HEX 




(4) 


SID SORT .HEX 


SORT.SYM 


(5) 


ED SORT .ASM 




(6) 


MAC SORT 




(7) 


TYPE SORT.SYM 


(8) 


SID SORT .HEX 


SORT.SYM 


(9) 


ED SORT .ASM 




(10) 


MAC SORT 




(ID 


SID SORT .HEX 


SORT.SYM 


(12) 


ED SORT .ASM 




(13) 


MAC SORT 




(14) 


LOAD SORT 




(15) 


SID SORT.COM 


SORT.SYM 


(16) 


SID SORT.COM 


SORT.SYM 


(17) 


SID S0RT.COM 


SORT.SYM 


(18) 


SID S0RT.COM 


SORT.SYM 


(19) 


ED SORT. ASM 




(20) 


MAC SORT 




(21) 


SID SORT .HEX 


SORT.SYM 


(22) 


ED SORT .ASM 




(23) 


MAC SORT 




(24) 


SID SORT .HEX 


SORT.SYM 


(25) 


ED SORT .ASM 




(26) 


MAC SORT $+S 





Lists initial SORT program. 

Shows the SORT symbol table. 

Shows the SORT HEX file. 

1st debugging session. 

1st re-edit of SORT program. 

1st reassembly of SORT. 

Shows new symbol table. 

2nd debugging session. 

2nd re-edit of SORT program. 

2nd reassembly of SORT. 

3rd debugging session. 

3rd re-edit of SORT. 

3rd reassembly of SORT. 

Create a COM file for SORT. 

4th debugging session. 

Re-entry to SID for debugging. 

Re-entry to SID for debugging. 

Re-entry to SID for debugging. 

4th re-edit of SORT. 

4th reassembly of SORT. 

5th debugging session. 

5th re-edit of SORT. 

5th reassembly of SORT. 

6th debugging session. 

6th (last) re-edit of SORT. 

6th (last) reassembly. 



Following the debugging sessions, the final corrected SORT program 
is given in its debugged form. 
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Three separate debugging sessions are then shown that use the 
HIST and TRACE utilities to monitor the execution of the tested SORT 
program. The operations shown here include: 



As a final example, a simple program that calls the BDOS is 
listed, followed by a single debugging session. This particular 
example shows the actions of SID when subroutines are traced, 
followed by calls on the CP/M BDOS. The operations in this case 
are : 



(27) SID HIST.UTL 

(28) SID TRACE. UTL 

(29) SID 



Load the HIST Utility. 
Load the TRACE Utility. 
Load SID, TRACE follows. 



(30) TYPE IO.PRN 

(31) SID 10. HEX IO.SYM 



List the 10 program 
Enter SID for debugging 
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1 /TYPE SORT.PRN 

; SORT PROGRAM IN CP/M ASSEMBLY LANGUAGE 

; ELEMENTS OF 'LIST' ARE PLACED INTO 

; DESCENDING ORDER USING BUBBLE SORT 



0100 






ORG 


100H 


; BEGINNING OF TPA 


0000 




REBOOT 


EQU 


0000H 


;CP/M REBOOT LOCATION 


0100 


213801 


SORT: 


LXI 


H.SW 




0103 


3601 




MVI 


M,l 


;SW = 1 


0105 


213901 




LXI 


H,I 


; INDEX TO SORT LIST 


0108 


3600 




MVI 


M,0 


;I = 



; COMPARE I WITH ARRAY SIZE 

COMP: ;HL ADORESS INDEX I 



010A 3A6201 




LDA 


N 


LENGTH OF VECTOR 


0100 


BE 




CMP 


M 


CHECK FOR N=I 


010E C21901 




JNZ 


CONT 


CONTINUE IF UNEQUAL 








END OF 


ONE PASS THROUGH LIST 


0111 


213801 




LXI 


H,SW 


NO SWITCHES? 


0114 


7E 




MOV 


A,M 


FILL A WITH SW 


0115 


B7 




OR A 


A 


SET FLAGS 








END OF SORT PROCESS, REBOOT 


0116 


C30000 


STOP: 


JMP 


REBOOT 


RESTART CCP 








CONTINUE THIS PASS 






CONT: 












> 


ADDRESSING I, SO LOAD LIST(I) 


0119 


5F 




MOV 


E.A 


LOW(I) TO E REGISTER 


011A 


1600 




MVI 


D,0 


HIGH(I) = 


one 


215A01 




LXI 


H.LIST 


BASE OF LIST 


011F 


19 




DAD 


D 


ADOR LISTf I ) 


0120 


7E 




MOV 


A,M 


LIST(I) IN A REGISTER 


0121 


23 




I NX 


H 


ADOR OF LISTU+1) 


0122 


BE 




CMP 


M 


LIST(I) :LIST( 1+1) 


0123 


DA3101 




JC 


INCI 


SKIP IF PROPER ORDER 






» 
> 


CHECK 


FOR LISTf I 


= LISTf 1+1) 


0126 


CA3101 




JZ 


INCI ;SKIP IF EQUAL 






1 


ITEMS 


ARE OUT OF ORDER, SWITCH 


0129 


4E 




MOV 


C.M 


OLD LISTf 1+1) TO C 


012A 


77 




MOV 


M,A 


NEW LIST*I+1) TO M 


012B 


2B 




DCX 


H 


ADOR LIST(I) 


012C 


71 




MOV 


M,C 


NEW LISTf I ) TO M 


012D 


213801 


> 


LXI 


H,SW ;SWITCH COUNT IS SW 


0130 


34 




INR 


M ;SW = SW + 1 






INCI: 


: INCREMENT INOEX 


I 


0131 


213901 




LXI 


H.I 




0134 


34 




INR 


M 


1 = 1 + 1 


0135 


C30A01 




JMP 


COMP ;T0 COMPARE I WITH N-'l 





SW: 


DATA AREAS 




0138 


DS 1 


; SWITCH COUNT 


0139 


I: 


DS 1 


; INDEX 


013A 


STACK : 


DS 32 


;16 LEVEL STACK 



015A 0503040A08LIST: DB 5,3,4,10, 8,130,10,4 

0162 08 N: DB S-LIST ; LENGTH OF LIST 

0163 END 
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(2) TYPE SORT.SYM 

^OblOA COMP 0119 CONT 0139 I 0131 INCI 015A LIST 

0162 N 0000 REBOOT 0100 SORT 015A STACK 0116 STOP 

0138 SW 

@TYPE SORT. HEX 
.1001000O21380136012139O136003A62O18EC21997 
:10011000012138017EB7C300005F1600215A011982 
:100120007E238EDA3101CA31014E772B71213801AD 
:080130003421390134C30A0136 
:09015A000503040A08820A0408E6 
: OOOOOOOOOO 







SID SORT. HEX SORT.SYM start SID with HEX and SYM files 

SID VERS 1.4 
SYMBOLS 
NEXT PC END 

0163 0100 55B7 Next free address is 163, Program Co unter is 100 

#D.LIST,+=N-1 and end of TP A is S5B7 

015A: 05 03 04 OA 08 82 

0160: OA 04 .. Display initial list of items to sort 

#G,.ST0P Execute test program until "STOP" symbol address encountered 

*01 16 .STOP Now at the STOP address, examine data list: 
#D.LIST,+=N-1 

015A: 05 03 04 OA 08 82 Hasn't changed! 

0160: OA 04 .. 

#XP where is the program counter? 

P=0116 100 reset PC back to beginning and try again with trace on: 



mo 



COMP: 



A=01 B=0000 D=0008 H=0138 S=0100 P=0100 LXI H,0138 .SW _ 

A=01 B=0000 D=0008 H=0138 S=0100 P=0103 MVI M,01 .SW sw ~ 1 

A=01 B=0O00 D=0008 H=0138 S=0100 P=0105 LXI H.0139 .1 1=0 

A=01 3=0000 0=0008 H=0139 S=0100 P=0108 MVI M,00 .1 



A=01 B=0000 D=0008 H=0139 S=0100 P=010A LDA 0162 .N N =[? 

A=08 B=0000 0=0008 H=0139 S=0100 P=010D CMP M=00 .1 

.... J A=08 B=0000 D=0008 H=0139 S=0100 P=010E JNZ 0119 .CONT 

CONT: No, so compare 

1 A=08 8=0000 D=0008 H=0139 S=0100 P=0119 MOV E,A LIST(i), LIST(i+l) 

1 A=08 8=0000 D=0008 H=0139 S=0100 P=011A MVI 0,00 

1 A=08 B=0000 0=0008 H=0139 S=0100 P-011C LXI H.015A .LIST 

1 a=08 8=0000 D=0008 H=015A S=0100 P=011F DAD D 

1 A=08 B=0000 D=0008 H=0162 S=0100 P=0120 MOV A,M .N What s this. 

1 A=08 B=0000 D=0008 H=0162 S=0100 P=0121 INX H wh V. dl ° we 

1 A=08 8=0000 D=0008 H=0163 S=0100 P=0122 CMP M=58 l etch N? 

C-M-I A=08 B=0000 D=0008 H=0163 S=0100 P=0123 JC 0131 .INCI 

INCI: 

C-M-I A=08 B»0000 0=0008 H=0163 S=0100 P=0131 LXI H.0139 .1 

*0134 Looks like we've discovered a bug! We have entered at "CONT" 

#G0 with iV in- the accumulator, rather than I, which is expected! 



5 ) ED SORT. ASM Back to the editor to make the changes 

#A Bring all the text into memory 

*V Enter Verify mode for line numbers, then find the place to change 
' *FADDRESSING 
*0LT 

; ADDRESSING I, SO LOAD LIST(I) Delete the line 

*KT 

MOV E, A ;L0W(I) TO E REGISTER 

*I 

LDA I ;L0AD I TO A REGISTER Insert the 

ctl-Z change 
*E Terminate the editing session 



1 
28 
28 
28 
28 
28 
28 
29 
29 
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MAC SORT 
CP/M MACRO ASSEM 2.0 

Ml! USE FACTOR ^-assembie the SORT program 

END OF ASSEMBLY 



TYPE SORT.SYM Hmf ' tabl ' : 



010A COMP 0119 CONT 013C I 0134 INCI 015D LIST 

0165 N 0000 REBOOT 0100 SORT 0150 STACK 0116 STOP 

0138 SW 



SID SORT. HEX SORT.SYM 
■un VFRS 1 4 

SYMBOLS l8t ' S try a9Qin ' i0ad the HEX md SYM f ile$ 

NEXT PC END 
0166 0100 55B7 

#P.ST0P $ et a "pass point" at STOP to prevent reboot 



#G 



Start (unmonitored) execution 



01 PASS 0116 .STOP We made it to the STOP label, check values 

A=7C B=0008 D=0081 H=013B S=0100 P=0116 JMP 0000 .REBOOT 

*0000 .REBOOT 

#H=N What's the value of the byte variable N? 

0082 #130 130? Very strange! How did that happen? 

#0. LIST, +7 Oh well, let's look at the data values: 

5o a. o« A; "no Thf >y are almost sorted, looks like we have 

*KnRT HFX SOme tr0Uble " ear tHe end 0f 0x0 VeCt0r ' 

fiiUKi.ntA Iet , s reioad ma chine code and try 

SeXT PC END QffaI '" : 

0166 0100 55B7 

#XP 

P=0100 Program counter remains at 0100, what 

jjip are the active pass points? 

01 0116 .STOP The one at STOP remains set, let's also 

#P.S0RT,FF monitor the SORT loop point, but not 

#G break right away. 

FF PASS 0100 .SORT Here's the first time through SORT 

A=7C 8=0008 D=0081 H=013B SO100 P=0100 LXI H.013B .SW 

01 PASS 0116 STOP ft stopped immediately! It doesn't look good! 

A=79 8=0008 D=0081 H=0138 S=0100 P=0116 JMP 0000 .REBOOT 

*O000 .REBOOT We know there should have been several loops 

#IS0RT.HEX through the SORT label, since the data is 

#R unordered. Let's try again — reload the code 

NEXT PC END (note that the reload is necessary here, since 

0166 0100 55B7 the data is initialized in the code area). 
#P 

01 0116 .STOP what active pass points exist? 

FE 0100 .SORT Wait a minute — referring back to the 

#G0 original listing, it appears that the code 

preceding the STOP label is incomplete: 
there should be a conditional jump back to 
the SORT label - maybe that's why the program 
never makes it back! 
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(^}eD SORT. ASM Oh well, back to the editor for a 

*#AV quick fix. Append all text (#A), and 

.1: *FST0P: enter Verify mode (V). Then find STOP. 

24: *0LT 

24: STOP: JMP REBOOT ;RESTART CCP 

24; *- Go up one line (-) 

23: ; END OF SORT PROCESS, REBOOT 

23: *I and enter insert mode (I) 

23: JNZ CONT ; CONTINUE IF NOT EQUAL 

24 : ; ctl-Z, and "return" 

25: E 

26: wait, I forgot the ctl-Z, now Tve got the E command in 

26: *- my input buffer. Type the ctl-Z, go back up one line, 
25: E delete the E, then end the edit 

25: *KT 

25: ; END OF SORT PROCESS, REBOOT 

25: *E OK, we made the change, now re-assemble 



MAC SORT Invoke the macro assembler with SORT as input. 

'CP/M MACRO ASSEM 2.0 
0169 

001H USE FACTOR 
END OF ASSEMBLY 

^ /SID SORT. HEX SORT.SYM Here we go again, I sure hope this is the 
ID VERS 1.4 i as t time ( D ut it probably isn't). 

SYMBOLS 
NEXT PC END 
0169 0100 55B7 

IP. SORT, FF s e t a p ass point at sort, with a high count. 

P ■ STOP also set a pass point at STOP with count 1, this 

#P will stop the first time through 

FF 0100 .SORT 
01 0119 .STOP 

#G Execute the test program 

FF PASS 0100 .SORT ^ frs£ tlme through SORT label: 
A=00 8=0000 D=0000 H=0000 S-0100 PO100 LXI H.013E .SW 

01 PASS 0119 .STOP Stopped again! Arrggh! 

-Z-E- A=00 B=006A D=0007 H=013E S=0100 P=0119 JMP 0000 .REBOOT 

*0000 .REBOOT 

Let's look at some values: 

H=N 

0008 #8 n=s, looks better than last time 

#D.LIST,+=N 

0160: 01 01 03 04 04 05 07 08 08 rhese values look a bit 

#IS0RT.HEX strange?! Try again: 

#R 

NEXT PC EN0 
0169 0100 55B7 

#0.LIST +=N-1 Machine code reloaded, display initial values: 
0160: 05 03 04 OA 08 82 OA 04 

Let's take a look at the process of switching 
two data items - the code appears down below 
the "CONT" label, so we'll disassemble a 
portion of the program. 
.LlSf 



NCI 
NCI 

Here's where the switch occurs, let's set a pass 
point here and watch the data addresses: 



R.CONT 






CONT: 






one 


LDA 


013F .1 


011F 


MOV 


E,A 


0120 


MVI 


D,00 


0122 


LXI 


H,0160 


0125 


0A0 





0126 


MOV 


A,M 


0127 


!NX 


H 


0128 


CMP 


M 


0129 


JC 


0137 .1 


012C 


JZ 


0137 .1 


012F 


MOV 


C,M 


#P12F,FF 




#P 






FE 0100 


.SORT 


01 0119 


. STOP 


FF 012F 
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#G 

FE PASS 0100 . 

-Z-E- A=00 B= 
FF PASS 012F 

— -I A=05 8= 
FE PASS 012F 

1 A=05 B= 

FD PASS 012F 

1 A=0A B- 

FC PASS 012F 

— E- A=82 B- 
*0130 
# 

#-P 

#IS0RT.HEX 
#R 

NEXT PC END 
0169 0100 55B7 
#L.C0NT+5 
0121 NOP 



SORT Here's the first pass through SORT 

006A 0=0007 H=013E S=0100 P=0100 LXI ,H,013E .SW 
Switching at address 161, looks OK! 

O06A D=0000 H=0161 S=0100 P=012F MOV C,M 

Switching at 162, looks good. 
'0003 D=0001 H=0162 S=0100 P=012F MOV C,M 

164 is the next to switch, looks good. 
■0004 0=0003 H=0164 S=0100 P=012F MOV C,M 

166 is probably the next one. 
=0008 D=0005 H=0166 S=0100 P=012F MOV C,M 
So what's wrong? This section of 
code seems to work. 

Clear all the pass points, and reload 
the machine code for another test. 



0122 
0125 
0126 
0127 
0128 
0129 
012C 
012F 
0130 
0131 
#G,129 

*0129 
#T10 



LXI 

DAD 

MOV 

INX 

CMP 

JC 

JZ 

MOV 

MOV 

DCX 



H.0160 
D 

A,M 

H 

M 

0137 . 
0137 . 
C,M 
M,A 
H 



.LIST 

Here's the code where the element 
switching occurs, let's watch the 

program switch the first element: 
INCI 
INCI 



— I 


A=05 


B=0000 


— I 


A=05 


B=0000 


— I 


A=05 


B=0000 




A=05 


B=0003 


— I 


A=05 


B=0003 




A=05 


B=0003 


— I 


A=05 


B=0003 


— I 


A=05 


B=0003 


*0137 


.INCI 





OK, here we are, ready to test and 

switch, if necessary. 
=0000 H=0161 S=0100 P=0129 
=0000 H=0161 S=0100 
=0000 H=0161 S=0100 



#D.LIST,+7 

0160: 03 05 04 OA 08 

#H=I 

0000 .REBOOT #0 
#G, . INCI 



=0000 H=0161 
=0000 H=0161 
■0000 H=0160 
■0000 H=0160 S=0100 
■0000 H=013E SO100 



JC 

P=012C JZ 
P=012F MOV 
S=0100 P=0130 MOV 
S=0100 P=0131 DCX 
S=0100 P=0132 MOV 
P=0133 LXI 
P=0136 INR 



. INCI 
.INCI 



0137 
0137 
C,M 
M,A 
H 

M,C .LIST 
H.013E .SW 
M=01 .SW 



Well, that went nicely - elements switched, SW=1 

82 OA 04 

The data looks good at this point. 

Proceed to the INCI label 

Here we are, let's look at the data: 



*0137 . INCI 
#D.LIST,+7 

0160: 03 05 04 OA 08 82 OA 04 

#H«I 

0000 .REBOOT #0 Looks good, trace past the label and break 

#T 

A=05 B=0003 0=0000 H=013E S=0100 P=0137 LXI H,013F .1 

*013A 

#G,.INCI Go to the INCI label again. 



*0137 .INCI 
#D.LIST,+=I 
0160: 03 04 .. 
#T 

... £- A=05 B=0004 0=0001 H=013E S=0100 P=0137 LXI H.013F .1 



Here we are (again), how's the data? 
Looks good, proceed past INCI 



*013A 
#G,.INCI 

*0137 .INCI 
#D.LIST,+=I 
0160: 03 04 05 
#G, .SORT, .STOP 



And loop again . . . 

Here we are (again), how's the data? 

Looks good, this is getting monotonous, let's 
go for it! Stop at either SORT or STOP 



*0119 .STOP Egad! Here we at the the STOP label. Why 

#D.LIST,+=I aren't we making it back to SORT? 

0160: 01 01 03 04 04 05 07 08 08 

# Tsk! Tsk! The data's messed up again. 
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#IS0RT.HEX Let's reload and try again. 
#R 

NEXT PC END 
0169 0100 55B7 
#1136, +3 

0136 INR M Here's where the swftch count is incremented 
INCI: 

0137 LXI H.013F .1 
013A 

#G, 136 Execute the program and break 
at SW = SW + 1 

*0136 

#D.LIST,+=I look at data values: 
0160: 03 . 

#U Use U to move past break address 

1 A=05 B=0003 D=0000 H=013E S=0100 P=0136 INR M=01 .SW 

*0137 .INCI it's actually easier to use the pass point feature 

#P136 if we want to view the action of the INR M, 

#G since the P command stops execution after the 
pass point is executed. 

01 PASS 0136 

1 A=05 B=0004 D=0001 H=013E S=0100 P=0136 INR M=02 .SW 

*0137 .INCI SW = 2, looks good. 
#0.LIST,+=I 

0160: 03 04 .. Data values look good. 

#S.N Let's change N to a smaller value so the program 

0168 08 4 doesn't loop so many times: 4 is a good number. 

0169 OA . End input with "." 
#G "CO" to pass point 

01 PASS 0136 Here we are, switch value is incremented: 

1 A=0A B=0008 0=0003 H=013E S=0100 P=0136 INR M=03 .SW 

*0137 .INCI Stopped at next instruction. 
#D.LIST,+=I 

0160: 03 04 05 08 Data values so far. 

#H=SW 

0004 #4 SW value at this point is 4. 

#TFFFF Let's watch it run for a few steps: 

A=0A B=0008 D=0003 H=013E S=0100 P=0137 LXI H.013F .1 

A=0A B=0008 0=0003 H=013F S=0100 P=013A INR M=03 .1 

A=0A B=0008 0=0003 H=013F S=0100 P=013B JMP 010A .C0MP 

C0MP: 

A=0A B=0008 0=0003 H=013F S=0100 P=010A LDA 0168 . N 

A=04 B=0008 0=0003 H=013F S=0100 P=010D CMP M=04 .1 

-Z-EI A=04 B=0008 D=0003 H=013F S=0100 P=010E JNZ 011C .C0NI 

-Z-EI A=04 B=0008 D=0003 H=013F S=0100 P=0111 LXI H,013E .SV, 

o-Z-EI A=04 B=0008 0=0003 H=013E S=0100 P=0114 MOV A,M .SW 

-Z-EI A=04 B=0008 0=0003 H=013E S=0100 P=0115 0RA A 

A=04 B=0008 0=0003 H=013E S=0100 P=0116 JNZ 011C .C0NT 

C0NT: 



*011F 
#60 



A=04 B=0008 D=0003 H=013E S=0100 P=011C LDA 013F .1 

Very interesting! We seem to be 
Let's & 0i B8c£% k tr?e T&W^VuW " S0Rr '' 



@ED SORT. ASM J „ , t t .. 

*#AVF0RA This is a sim P le cn <mge: append all text, enter line 

22- *0LT verify mode, find "ORA" and make the change.- 

22': ORA A ;SET FLAGS 

22: * "return" to move down one line 

23: JNZ C0NT ;C0NTINUE IF NOT EQUAL 

23: *SC0NT!ZS0RT!Z0LT Substitute SORT for CONT 

23: JNZ SORT ; CONTINUE IF NOT EQUAL 

23: * "return" to move down another line 
24: ; 

24: * "return" again. 

25: ; END OF SORT PROCESS, REBOOT 

25: *E End the edit 
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(^}mac sort 
cp/m macro assem 2.0 

0169 Call out MAC for another assembly. 

001H USE FACTOR 
END OF ASSEMBLY 



® 



U 1L0A0 SORT r t . . . 

' Just for a little variation, we'll create a 

FIRST ADORESS 0100 s ORT.COM file for testing under SID. 
LAST A00RESS 0168 
BYTES READ 0047 
RECORDS WRITTEN 01 



^ /SID SORT.COM SORT.SYM 

ID VERS 1.4 Back to SID, using the COM and SYM files 

SYMBOLS 
NEXT PC END 
0180 0100 55B7 

#P.STOP Set a pass point at STOP to prevent reboot 

#D.LIST,+=N-1 Here's the original data: 

0160: 05 03 04 OA 08 82 OA 04 

*G Unmonitored GO 

Oops! We didn't get control back, there must 
be an infinite loop - we can get control back by 
63K CP/M VERS 1.3 forcing a front panel RST 7 (interrupt 7), 

or simply bail-out with a cold start. 



ID S0RT.C0M SORT.SYM 
SID VERS 1.4 Let's start again, but be a little more selective 
SYMBOLS in setting breakpoints. 

NEXT PC END 
0180 0100 55B7 

#P.ST0P Set a pass point at STOP, as before 

#P.S0RT,FF and one at SORT with a pass count of 255. 

#-G GO with pass trace disabled. 

01 PASS 0100 Stopped with 255 passes through SORT - too many! 

A=01 B=006A D=00FF H=013E S=0100 PO100 LXI H.013E 

*0103 

rD.LIST,+=N-l How's the data? 
0160: 03 . 

#H=N Hmmm... looks like N was destroyed. 

0000 .REBOOT #0 

#H-I 

0000 .REBOOT #0 

#G,.C0MP There's a good possibility that we're running off 

the end of the LIST vector into the variable N, 
*010A .C0MP let's stop at the COMP label and watch the end test. 
#T5 

A=01 B=006A D=00FF H=013F S=0100 P=010A LDA 0168 .N 

A=00 B=006A D=00FF H=013F S=0100 P=0100 CMP M=00 .1 

-Z-EI A=00 B=006A D=00FF H=013F SO100 P=010E JNZ 011C .C0NT 
-Z-EI A=00 B=006A D=00FF H=013F S=0100 P=0111 LXI H.013E .SW 
-Z-EI A=00 BO06A DO0FF H=013E S=0100 P-0114 MOV A,M .SW 
*0115 Hey, this isn't going to work! We'll be comparing 
#G0 LIST(N-l) with LIST(N), but the last LIST element is 

at LIST(N-l). Let's try a quick fix. 
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510 S0RT.COM SORT.SYM 
1.4 



510 VERS 

SYMBOLS 

NEXT PC ENO 

0180 0100 55B7 

#L.C0MP 

COMP: 
OlOA LDA 
010D CMP 
010E JNZ 
0111 LXI 
0114 MOV 



Let's re-enter SID with a clean memory 
image, and look at the machine code 
below the "COMP" label. 



#A10A 




OlOA JMP 


200 


0100 




#A200 




0200 LDA 


,N 


0203 OCR 


A 


0204 CMP 


M 


0205 JNZ 


.C0NT 


0208 JMP 111 


020B 




#P205,FF 




#P.ST0P 




#PU1,FF 




#S.N 




0168 08 4 




0169 00 . 




#G 





0168 
M 

one 

H,013E 
A,M 



FF PASS 0205 

—EI A=03 8=0000 
FE PASS 0205 

.—I a=03 B=0003 
FD PASS 0205 

— -I A=03 8=0004 
FC PASS 0205 

-Z-EI A=03 8=0004 
FF PASS 0111 

-Z-EI A=03 B=0004 
FB PASS 0205 

—EI A=03 B=0004 
FA PASS 0205 

1 A=03 B=0004 

F9 PASS 0205 

1 a=03 B=0004 

F8 PASS 0205 

-Z-EI A=03 B=0004 
FE PASS 0111 

-Z-EI A=03 B=0004 
*0114 

#D.LIST,+=N-1 
0160: 03 04 05 OA 



-UFFFF 
-Z-EI A=03 
*013B 
#H=N 
0004 #4 
#H=I 
0002 #2 



=0004 



N Here's the reference to N - let's change this 
to N-l with a "hot patch" in memory, to see 
CONT if n works, then we'll go back to the 
SW original source program and make the 
necessary changes. We're not using the area 
of memory starting at 0200, so patch a jump 
over the LDA instruction, and fix-up some 
patch code. 

Replace the LDA instruction which now has JMP 200. 
N-l in accumulator (N better be 2 or larger!) 
and compare with memory (HL addresses I), 
jump to CONT if continuing, otherwise 
jump back to the next instruction in sequence 
after the patch. 

Set a pass point to watch the JNZ take place 
and catch any returns to the CCP. 
Set a pass point at the patch return address. 
Reduce the size of N for this test to 4. 



Everything is ready, let's go- 
First pass through the patch code: 

0=0000 H=013F S=0100 P=0205 JNZ 011C .CONT 
Went to CONT that time, second pass: 

0=0000 H=013F S=0100 P=0205 JNZ 011C .CONT 
Went to CONT again, next pass: 

D=0001 H=013F S=0100 P=0205 JNZ 011C .CONT 
And so-forth: 

D=0002 H=013F S=0100 P=0205 JNZ 011C .CONT 
Must be the end of one cycle: 

D=0002 H=013F S=0100 P=0111 LXI H,013E .SW 
Now back through the patch code: 

0=0002 H=013F S=0100 P=0205 JNZ 011C .CONT 

D=0000 H=013F S=0100 P=0205 JNZ 011C .CONT 
D=0001 H=013F S=0100 P=0205 JNZ 011C .CONT 
0=0002 H=013F S=0100 P=0205 JNZ 011C .CONT 

0=0002 H=013F S=0100 P=0111 LXI H,013E .SW 

This is getting monontonous again, so 
push the "return" key to stop the action. 
" " Data looks good, run in monitored mode: 

0=0002 H=013E S=0100 P=0114 MOV A,M 
Push the "return" key to abort early. 
Value of N is still 4 (that's nice!) 
Value of I is currently 2. This program 
should have stopped, but didn't for some 
reason. 
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SID S0RT.COM SORT.SYM 



END 



SID VERS 1. 
SYMBOLS 
NEXT PC 
0180 0100 55B7 
#S.N 

0168 08 2 

0169 00 . 
#S.LIST 

0160 05 

0161 03 

0162 04 



Let's try another approach. Suppose we 

cpnstmct a really triviaLcase:, we'll set 
W = 2 (two items to sort), and 

LIST(O) = 0, LIST(l) = 1 



1 



P. STOP 

#TFFFF 

A=00 

A=00 

A=00 

A=00 

C0MP: 

A=00 

A=02 

1 A=02 

CONT: 

1 

1 

1 

1 

1 

1 

C-ME- 
INCI: 

C-ME- 

C-ME- 

C 

C0MP: 

C 

C 

1 

CONT: 

1 

1 

1 

1 

1 

1 

1 

C-M-- 
INCI: 

C-M-- 

C-M-- 

C-— 
COMP: 

C 

C 

-Z-EI 

-Z-EI 

-Z-EI 

-Z-EI 



A=01 
A=02 
A=02 
A=02 
A=02 
A=01 
A=01 



Things are ready to go, run completely traced: 



8=0000 D=0000 H=0000 S=0100 P=0100 LXI 

B=0000 D=0000 H=013E S=0100 P=0103 MVI 

8=0000 D=0000 H=013E S=0100 PO105 LXI 

B=0000 D=0000 H=013F S=0100 P=0108 MVI 

8*0000 0=0000 H=013F S=0100 P=010A LDA 

B=0000 D=0000 H=013F S=0100 P=010D CMP 

B=0000 D=0000 H=013F S=0100 P=010E JNZ 



A=02 
A=00 
A=00 
A=00 
A=00 
A=00 
A=00 
A=00 
A=00 

A=00 
A=00 
A=00 

A=00 
A=02 
A=02 

A=02 
A=01 
A=01 
A=01 
A=01 
A=01 
A=01 
A=01 
A=01 

A=01 
A=01 
A=01 



0000 D=0000 
0000 0=0000 
0000 0=0000 
0000 D=0000 
0000 0=0000 
0000 D=0O00 
0000 D=0000 
0000 D=0000 
0000 D=0000 
Not swi 
0000 D=0000 
0000 0=0000 
0000 D=0000 



H=013F 
H=013F 
H=013F 
H=013F 
H=0160 
H=0160 
H=0160 
H=0161 
H=0161 
tched.' 
H=0161 
H=013F 
H=013F 



S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 

S=0100 
S=0100 
S=0100 



P=011C LDA 
P=011F MOV 
P=0120 MVI 
P=0122 LXI 
P=0125 
P=0126 
P=0127 
P=0128 
P=0129 



DAD 
MOV 
INX 
CMP 
JC 



P=0137 LXI 
P=013A INR 
P=013B JMP 



H,013E .SW 
M,01 .SW 
H,013F .1 
M,00 .1 

0168 .N 
M=00 .1 
011C .CONT 

013F .1 
E,A 
D,00 
H,0160 
D 

A,M .LIST 
H 

M=01 

0137 . INCI 

H,013F .1 
M=00 .1 
010A .COMP 



LIST 



8=0000 D=0000 H=013F S=0100 P=010A LDA 0168 .N 
8=0000 0=0000 H=013F S=0100 P=010D CMP M=01 .1 
B=0000 D=0000 H=013F S=0100 PO10E JNZ 011C .CONT 



B=00O0 
B=0000 
B=0000 
B=0000 
8=0000 
B=0000 
8=0000 
8=0000 
8=0000 

8=0000 
B=0000 
8=0000 

8=0000 
B=0000 
B=0000 
8=0000 
B=0000 
B=0000 
3=0000 



D=0000 H=013F S=0100 

D=0000 H=013F S=0100 

D=0001 H=013F S=0100 

D=0001 H=013F S=0100 

D=0001 H=0160 S=0100 

D=0001 H=0161 S=0100 

0=0001 H=0161 S=0100 

D=0001 H=0162 S=0100 

0=0001 H=0162 S=0100 

Not switched (again)! 

'O-uOOl H=0162 S=0100 

0=0001 H=013F S=0100 

0=0001 H=013F S=0100 



P=011C LDA 
P=011F MOV 
P=0120 MVI 
P=0122 LXI 
P=0125 DAD 
P=0126 MOV 
P=0127 INX 
P=0128 CMP 
P=0129 JC 

P0137 LXI 
P=013A INR 
P=0138 JMP 



013F 
E, A 
D,00 
H,0160 
D 

A,M 

H 

M=04 
0137 . 



.1 



.LIST 



INCI 



0=0001 H=013F 
D=0001 H=013F 
0=0001 H=013F 
D=0001 H=013F 
D=0001 H=013E 
D=0001 H=013E 



SORT: 
*0103 



0=0001 H=013E 
No items were 

— A=01 B=0000 D=0001 H=013E 



S=0100 

S=0100 

S=0100 

S=0100 

S=0100 

S=0100 

S=0100 P 

switched 

S=0100 P 



^OlOA LDA 
■0100 CMP 
'010E JNZ 
■0111 LXI 
'0114 MOV 
0115 
0116 



OR A 
JNZ 



H,013F .1 
M=01 .1 
010A .COMP 

0168 .N 
M=02 .1 
011C .CONT 
H.013E .SW 
A,M .SW 
A 

0100 .SORT 



- SW not set to 01 
=0100 LXI H,013E .SW 
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® 



ED SORT. ASM 
~*#AVFS0RT:!Z01T 





o 


SORT: 


LXI 


U CI 1 


Q 









7 








7 


*2 






y 




MVI 


M,l 


y 


*2S1!Z0!Z0LT 


Q 




MVI 


m r\ 
M,U 


9 


*_ 




8 


SORT: 


LXI 


H,SW 


8 


*I 




8 




MVI 


A,l 


9 




STA 


SW 


10 








10 


*E 







/MAC SORT 
^-fP/M MACRO ASSEM 2.0 
016E 

001H USE FACTOR 
END OF ASSEMBLY 



Back to the editor- change the 
entry code to initialize SW 



;SW = 1 
;SW = 

;SW = 1 FIRST TIME THRU 
Re-assemble, again 



21 ^GID SORT. HEX SORT.SYM 
sID VERS 1.4 We've fixed the SW initialization problem, which 

SYMBOLS should halt the program at the proper time, but 

NEXT PC END w « ma y still have a problem with the end of 
016E 0100 55B7 LIST test (remember that "hot patch"?). 
#D.LIST,+=N Here's the initial data: 

0165: 05 03 04 OA 08 82 OA 04 08 

#G,.ST0P 

GO, unmonitored to the STOP (how's that for 
*011E .STOP confidence?). 
#D.LIST,+=N We made it, here's the data: 

0165: 03 04 04 05 08 08 OA OA 08 7B 82 

0170: E5 . Data is sorted in ascending order, but there's too 

#IS0RT.HEX much of it! We still have the problem that N is 

#R altered during execution. 

a^I „JL rcSi Let's reload and make sure we Jcnow what the 
Olot OlOU 55B/ 

#P.S0RT 

#G 



sVl b a er pass~ point at SORT, check N 



01 PASS 0105 .SORT Here's the first pass through SORT: 

-Z-E- A=01 B=0004 D=000A H=0143 SO100 P=0105 LXI H.0143 .SW 
*0108 
#H=N 
0008 #8 
#G 



Break at 0108, check value of N: 

OK initially, continue the execution with G. 



01 PASS 0105 .SORT We have passed through the data once: 

A=75 B=002A D=007A H=0143 S=0100 P=0105 LXI H.0143 .SW 

*0108 



#H=N 

007B #123 ' . ' 

IISORT.HEX 

#R 

NEXT PC END 
016E 0100 55B7 
#G,.INCI 



N has been altered, which we expected, since we 
are testing LIST(N-l) against LIST(N) and performing 
a switch if unordered. 

Let's reload and scope in on the problem: 
Stop at. the point where I becomes I + 1: 



01 PASS 0105 .SORT Oops.' The initial pass point is still set. 

A=01 B=002A D=007A H=0143 S=0100 P=0105 LXI H,0143 .SW 

*0108 



#-P 

#G,.INCI 

*013C .INCI 
#H=N 
0008 #8 
#G,.C0NT 

♦0121 .C0NT 
#G,.INCI 



Clear ail pass points. 
Now, try again: 

Stopped at first entry to INCI, check value of N: 
N is still 8, looks good. 

Go to the CONT label, then stop at INCI. 
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INCI 



*013C 
#H=N 
0008 #8 
#P.INCI,6 
#-G 

01 PASS 013C 
— E- A=82 E 
*013F 
#H=N 
0008 #8 
#H*I 
0006 #6 



Back at INCI now. Check value of N 

Remains at 8. If we keep this up, we'll be typing 
break addresses all day. We can run the next few passes 
through INCI automatically by setting a pass count (use 6 
in this case), then run with -G to disable intermediate 
traces. We now stop 6 iterations later: 
=0004 0=0006 H=0143 S=0100 P=013C LXI H.0144 

Check N: remains at 8, then 
check I to compare passes: 1=0,1,2,2,4,5,6 has been 
executed. We are now about to set I = 7 but the test 
at COMP is "JNZ" which allows execution one too many 
times (which we already know about). 



22 /ED SORT. ASM 
#AV 



1: 


*FLDA 




17: 


*0LT 




17: 




LDA 


17: 


* 




18: 




CMP 


18: 


*I 




18: 




DCR 


19: 




(NO' 


20: 


'ctl-Z 




20: 


*F*I 




49: 


*0T 




49: 




MOV 


49: 




MOV 


49: 


*F32 




64: 


*0LT 




64: 




OS 


64: 


*2KT 




64: 






64: 


*e 





Back to the editor, change the end of LIST test 
to compare I with N-i rather than N. 

N ; LENGTH OF VECTOR 

"return" to go to next line 
M ;CHECK FOR N=I 

Insert the instruction before the "CMP" opcode. 
A ;N-1 IN A REGISTER 

NOTE THAT N MUST BE 2 OR LARGER) 

Now a little clean-up work - there is a typo in 
a comment line at address 012A in the listing: 
M,A ;NEW LIST*I*-C-DI(!Z0LT 
M,A ;NEW LIST(I+1) TO M Looks better now. 

We are not using the 8080 stack, so get rid of it. 



32 



;16 LEVEL STACK 



® 



MAC SORT 
P/M MACRO ASSEM 2.0 
014F 

001H USE FACTOR 
END OF ASSEMBLY 



Complete the edit. 



Re-assemble the source program. 



<3 



SID SORT. HEX S0RT.SYM 
ID VERS 1.4 Back £0 S/D 

SYMBOLS 
NEXT PC EN0 
014F 0100 55BF 

#0.LIST,+=N /nUiaI data: 

0146 : 05 03 04 OA 08 82 OA 04 08 . . . 
#G,ST0P 



this should be the last time! 



#G,.ST0P 

*011F .STOP 
#D.LIST,+=N 



0146: 03 04 04 05 08 OA OA 82 08 
#H=N 
0008 #8 
#G0 



Ok, ok. Let's try it with an "address reference" to 
the label STOP: 

That's better, now look at the data: 
hooray! It's finally sorted. 



Is N ok? Yes, it's still 8. 

Hold it! The data is in ascending order, but it is 
supposed to be in descending order! This will 
be an easy fix. 
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; SORT PROGRAM IN CP/M ASSEMBLY LANGUAGE 

; ELEMENTS OF 'LIST' ARE PLACED INTO 

; DESCENDING ORDER USING BUBBLE SORT 

*SDES!ZASC!ZOLT 

; ASCCENDING ORDER USING BUBBLE SORT 

*SCC!ZC!ZOLT 

; ASCENDING ORDER USING BUBBLE SORT 

*E Took care of that problem. 

26)mac SORT s+s 

^TP/M MACRO ASSEM 2.0 
014F Re-assemble with the symbol table option. 

001H USE FACTOR 
END OF ASSEMBLY 

At this point, we have checked-out this particular SORT program using this 
particular set of data items. This does not, of course, mean that the program is fully 
debugged. There could be cases which are not tested properly since we have not 
included all boundary conditions (the data items 00 and FF, for example, should be 
included). Further, there are program segments which could be incorrect, but which 
have no negative effects on the program. The initialization of SW to the value I 
before the label SORT, for example, does not affect the program, but is superfluous. 
We now have a program which appears to work, but must undergo further tests before 
it is considered a production program. 
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SORT PROGRAM IN CP/M ASSEMBLY LANGUAGE 
ELEMENTS OF 'LIST' ARE PLACED INTO 
ASCENDING ORDER USING BUBBLE SORT 



0100 




ORG 


100H 


BEGINNING OF TPA 


0000 = 


REBOOT 


EQU 


OOOOH 


;CP/M REBOOT LOCATION 


0100 3E01 




MVI 


A,l 




0102 324401 




STA 


SW 


;SW = 1 FIRST TIME THRU 


0105 214401 


SORT: 


LXI 


H,SW 




0108 3600 




MVI 


M,0 


;SW = 


010A 214501 




LXI 


H,I 


; INDEX TO SORT LIST 


010D 3600 




MVI 


M,0 


;I = 



; COMPARE I WITH ARRAY SIZE 

COMP: ;HL ADDRESS INDEX I 



010F 


3A4E01 




LDA 




N ;LENGTH OF VECTOR 


0112 


3D 




OCR 




A ;N-1 IN A REGISTER 






l 


(NOTE 


THAT N MUST BE 2 OR LARGER) 


0113 


BE 




CMP 




M ;CHECK FOR N=I 


0114 


C22201 




JNZ 




CONT ; CONTINUE IF UNEQUAL 






I 

» 


END 


OF 


ONE PASS THROUGH LIST 


0117 


214401 




LXI 




H,SW ;N0 SWITCHES? 


011A 


7E 




MOV 




A,M ;FILL A WITH SW 


0118 


B7 




OR A 




A ;SET FLAGS 


one 


C20501 




JNZ 




SORT jCONTINUE IF NOT EQU/ 






} 


END 


OF 


SORT PROCESS, REBOOT 


011F 


C30000 


STOP: 


JMP 




REBOOT ;RESTART CCP 



; CONTINUE THIS PASS 

CONT: 



0122 


3A4501 




LDA 


I 


LOAD I TO A REGISTER 


0125 


5F 




MOV 


E,A 


LOW(I) TO E REGISTER 


0126 


1600 




MVI 


D,0 


HIGH(I) = 


0128 


214601 




LXI 


H.LIST 


BASE OF LIST 


012B 


19 




DAD 


D 


ADOR LIST(I) 


012C 


7E 




MOV 


A,M 


LIST(I) IN A REGISTER 


012D 


23 




INX 


H 


ADDR OF LISTU+1) 


012E 


BE 




CMP 


M 


LIST(I):LIST(I+1) 


012F 


DA3D01 




JC 


INCI 


SKIP IF PROPER ORDER 






> 


CHECK 


FOR LIST(I) •= LIST(I+1) 


0132 


CA3D01 




JZ 


INCI ;SKIP IF EQUAL 






* 


ITEMS 


ARE OUT OF ORDER, SWITCH 


0135 


4E 




MOV 


C,M ;OLD LIST(I+1) TO C 


0136 


77 




MOV 


M,A ;NEW LIST(I+1) TO M 


0137 


2B 




OCX 


H ;ADDR LIST(I) 


0138 


71 




MOV 


M,C ;NEW LIST(I) TO M 


0139 


214401 




LXI 


H,SW ;SWITCH COUNT IS SW 


013C 


34 




INR 


M ;SW = SW + 1 






INCI: 


; INCREMENT INDEX 


I 


013D 


214501 




LXI 


H,I 




0140 


34 




INR 


M 


1 = 1 + 1 


0141 


C30F01 




JMP 


COMP ;T0 COMPARE I WITH N-l 






1 


DATA 


WEAS 




0144 




SW: 


DS 


1 ; SWITCH COUNT 


0145 




I: 


DS 


1 ; INDEX 


0146 


0503040A08LIST: 


DB 


5,3,4,10, 


8,130,10,4 


014E 


08 


N: 


D8 


S-LIST ;LENGTH OF LIST 


014F 






END 







010F COMP 0122 CONT 0145 I 013D INCI 0146 LIST 

014E N 0000 REBOOT 0105 SORT 011F STOP 0144 SW 
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■27 KID HIST.UTL Start SID with the HIST utility 
SID VERS 1.4 

TYPE HISTOGRAM BOUNDS 100,200 Monitor 0100 through 0200. 
. INITIAL = 5221 

.COLLECT = 5224 Entry point addresses in HIST. 
.DISPLAY = 5227 

#IS0RT.HEX SORT.SYM Load tne S ORT program with symbols. 
*R 

SYMBOLS Program loaded, now loadinq symbols. 
NEXT PC END 
0600 0100 51B7 

#P .STOP Permanent break at STOP address. 

#P . S0RT.3 Execute to "steady state" conditions by 

*-G passing the SORT label three times before break. 

"-G" prevents intermediate pass traces. 

01 PASS 0100 

A=02 B=0004 0=0006 H=013F S=0100 P=0100 LXI H,013F 

*0103 We're now at the third pass through SORT. 

#-P .SORT Remove the pass point at SORT, run monitored 

#UFFF , . COLLECT f rom tn i s ooi'nt for 0FFF steps, collect data. 

A=02 8=0004 D=0006 H=013F S=0100 P=0103 MVI M,01 .5W 

*°!27 Stopped after OFFFsteps, display collected data: 

#C. DISPLAY 

HISTOGRAM: 

AD OR RELATIVE FREQUENCY, LARGEST VALUE = 0309 

0100 ***** 
0104 ** 

Q1Q3 ********************** most frequently executed address: 

010C *********************************************************** 
0110 ** 
0114 ******* 

011C ***************** 

0120 **************************************************** 

0124 ********************************** 

0128 **************************************************** 

012C ***** 

0130 

0134 

0138 ********************************** 
013C ***************** 

0200 * 

#L10C What's happening around the most frequently executed address? 

010C LXI B.BE3D „,...,. J , , _ 

010F JNZ 01 ID C0NT ^ hts ls where the end of LIST test takes place, 

0112 LXI H 013F SW so ' s reasonable that this segment of code would 

0115 MOV a'm ^e executed heavily. We could improve performance 

0116 0RA a' ^ reciuct "? the length of this segment. The value 

0117 JNZ 0100 SORT °f could, for example, be maintained in register 
jjgp. ' C throughout the computations, while the value of 

011A JMP 0000 .REBOOT 7 cou!d be ^P' register E, with 00 in D. 

fLllC There is also heavy execution around location 011C. 

011C NOP 
CONT: 

011D L0A 0140 . 1 Tht's is where we go on each element comparison 

0120 MOV E,A whether we switch elements or not. 

0121 MVI D,00 

0123 LXI H.0161 .LIST 

0126 DAD D 

0127 MOV A.M 

0128 INX H 

0129 CMP M 

012A JC 0138 . INCI 

0120 JZ 0138 . INCI 
#G0 
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(2B)sid trace. utl 

^"SID VERS 1.4 
INITIAL » 5321 
COLLECT * 5324 
DISPLAY - 5327 

REAOY FOR SYMBOLIC BACKTRACE 



Load the TRACE utility with SID. 



TRACE entry points. 



Indicates that assembler/disassembler is present. 



IISORT.HEX SORT.SYM 
#R 

SYMBOLS 
NEXT PC END 
0600 0100 52B7 
IP.STOP 
#P.C0NT,3 
IUFFFF, .COLLECT 



Ready the SORT program and symbol table. 
Load program and symbols to memory. 



Permanent break at the STOP label. 

Pass through CONT three times before stopping. 

Untrace mode, print intermediate pass points. 

H,013F .SW 



A=00 8=0000 0=0000 H=0O00 S=0100 P=0100 LXI 

03 PASS 0110 .CONT 

1 A=07 8=0000 0=0000 H=0140 S=0100 P*011D LDA 0140 .1 

02 PASS 0110 .CONT 

---EI A=07 B=0OO3 D=0000 H=0140 S=0100 P=011D LDA 0140 .1 
01 PASS 011D .CONT 
— EI A=07 B=0004 
*0120 

#C. DISPLAY 
BACKTRACE: 
CONT: 

LDA 0140 .1 
JNZ 0110 .CONT 
CMP M 
OCR A 



D=0001 H=0140 SO100 P=011D LDA 0140 .1 
Stopped on the third pass. 
Display the backtrace from CONT. 

Most recently executed instruction. 



011D 
010F 
010E 
010D 

COMP: 
OlOA 
013C 
0138 

INCI: 
0138 
0137 
0134 
0133 
0132 
0131 
0130 
0120 
012A 
0129 
0128 
0127 
0126 
0123 
0121 
0120 

CONT: 
0110 
010F 
010E 
010D 

COMP: 
OlOA 

#G0 



LDA 
JMP 
INR 

LXI 

INR 

LXI 

MOV 

OCX 

MOV 

MOV 

JZ 

JC 

CMP 

I NX 

MOV 

DAD 

LXI 

MVI 

MOV 

LDA 
JNZ 
CMP 
DCR 



0169 
OlOA 
M 



.N 

.COMP 



H.0140 
M 

H.013F 

M,C 

H 

M,A 

C, M 

0138 
0138 
M 
H 

A,M 

D 

H.0161 

D, 00 

E, A 



.SW 



.INCI 
.INCI 



.LIST 



0140 
0110 
M 
A 



.1 

.CONT 



LDA 0169 .N 



Least recently executed instruction, 
(aborted with "return") 
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29;sio 

>I0 VERS 1.4 
#-A 

# ITRACE . UTL 
#R 

INITIAL = 5921 
COLLECT = 5924 
DISPLAY = 5927 

JylSf ^S RESS BACKTRACE No ^^/disassembler 'present 
IISORT.HEX SORT.SYM Ready the S0RT program 

Read to memory. 



Start SID without loading any programs. 

Remove assembler/disassembler package. 

Ready the TRACE utility. 

Read the TRACE package to memory. 

TRACE entry point addresses. 



#R 

SYMBOLS 
NEXT PC END 
0600 0100 5887 

#P STOP Permanent break at STOP address, 

#P . C0NT 3 P ass P ^ at with P° ss com t 3 

I-UFFFf' .COLLECT ^un monitored, collect data, no intermediate 

A=00 B=0000 0=0000 H=0000 S=0100 P=0100 21 013F pass information. 

01 PASS 011D 

— EI A=07 B=0004 D=0001 H=0140 S=0100 P=011D 3A 0140 
*0120 Stopped on third pass through CONT 

#C. DISPLAY 

BACKTRACE: most recent addresses 

011D 010F 010E 010D 010A 013C 013B 0138 

0137 0134 0133 0132 0131 0130 0120 012A 

0129 0128 0127 0126 0123 0121 0120 011D 

010F 010E 010D 010A 013C 013B 0138 0137 

0134 0133 0132 0131 0130 012D 012A 0129 

0128 0127 0126 0123 0121 0120 011D 010F 

010E 010D 010A 0108 0105 0103 0100 least recent address. 

#G0 



3QHYPE I0.PRN 



0100 
0000 = 
0005 = 
0002 = 

0100 315401 
0103 C31501 



0106 OE02 



SIMPLE BDOS OUTPUT PROGRAM 



REBOOT 

BOOS 

CONOUT 



ORG 
EQU 
EQU 
EQU 

LXI 
JMP 



100H 



0005H 
2 



BEGINNING OF TPA 
REBOOT ENTRY POINT 
BDOS ENTRY POINT 
CONSOLE OUTPUT # 



SP, STACK; LOCAL STACK 
START ; START EXECUTION 



WRCHAR: ;WRITE CHARACTER FROM REGISTER A 



MVI 



C, CONOUT 



CONSOLE OUTPUT # 



0108 5F 




MOV 


E,A 


CHARACTER TO E 


0109 C30500 




JMP 


BDOS 


RET 


THROUGH BDOS 




WRMSG : 


; WRITE 


MESSAGE STARTING AT HL 'TIL 00 


OlOC 7E 




MOV 


A,M 


NEXT 


CHARACTER 


0100 B7 




OR A 


A 


00? 




010E C8 




RZ 




RETURN IF SO 


010F C00601 




CALL 


WRCHAR 


OTHERWISE WRITE IT 


0112 C30C01 




JMP 


WRMSG 


FOR 


ANOTHER CHARACTER 




START: 


: BEGINNING OF MAIN PROGRAM 


0115 212A01 




LXI 


H, WALLAMSG 


;PART 1 OF MESSAGE 


0118 CD0C01 




CALL 


WRMSG 




;WRITE IT 


011B 212A01 




LXI 


H, WALLAMSG 


;PART 2 OF MESSAGE 


011E CDOC01 




CALL 


WRMSG 




;WRITE IT 


0121 213001 




LXI 


H, WASHMSG 


;PART 3 OF MESSAGE 


0124 CDOC01 




CALL 


WRMSG 






0127 C30000 


STOP: 


JMP 


REBOOT 




;ST0P THE PROGRAM 






DATA AREAS 








WALLAMSG: 








012A 57414C4C41 


DB 


'WALLA ' 








WASHMSG 










0130 57415348 




DB 


'WASH' 






0134 




OS 


32 


;16 LEVEL STACK 




STACK : 










0154 




END 
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SID 10. HEX 10. SYM 
ID VERS 1.4 
SYMBOLS 
NEXT PC END 
0134 0100 55A9 
#G,.WRMSG 



Load the test program using the HEX and SYM files. 



GO from 0100 to the first call on WRMSC 



*010C 
#T100 



WRCHAR: 



Now trace from the WRMSG subroutine: 



.WRMSG 

A=00 B=0000 D=0000 H=012A S=0152 P=010C MOV 

A=57 3=0000 D=0000 H=012A S=0152 P=010D 0RA 

A=57 B=0000 D=0000 H=012A S=0152 PO10E RZ 

A=57 8=0000 0=0000 H=012A S=0152 P=010F CALL 

•- A=57 8=0000 D=0000 H=012A S=0150 P=0106 MVI 

- A=57 B---0002 D=0000 H=012A S=0150 P=0108 MOV 

-- A=57 B=0002 0=0057 H=012A S=Q150 P=0109 JMP 



A,M . WALLAMSG 
A 



0106 

C,02 

E,A 

0005 



BOOS: 



-Z-E- 
WRMSG: 
-Z-E- 
-Z-E- 
-Z-E- 
-Z-E- 
-Z-E- 
WRMSG: 
-Z-E- 
-Z-E- 



WRCHAR: 



A=57 B=0002 D=0057 H=012A S=0150 P=0005 JMP 55AA 
A=57 B=0002 D=0057 H=012A S=0150 P=55AA JMP 5CA4 
A=57 8=0002 0=0057 H=012A S=0150 P=5CA4 XTHL 
A=57 B=0002 D=0057 H=0112 SO150 P=5CA5 SHLD 6D52 
A=57 B=0002 0=0057 H=0112 S=0150 P=5CA8 XTHL 
A=57 B=0002 0=0057 H=012A S=0150 P=5CA9 JMP 
A=00 B=0000 0=0200 H=793B S=0152 P=0112 JMP 



A=00 
A=00 
A=00 
A=00 
A=00 

A=00 
A=57 
A=57 
A=57 

A=57 
A=57 



3=0000 D=0200 H=793B 
B=0000 D=0200 H=793B 
8=0000 D=0200 H=7938 
8=0000 0=0200 H=793B 
B=0000 D=0200 H=012A 



0152 
0152 
0152 



P=010C MOV 
P=010D ORA 
P=010E RZ 



6E06W 
010C 

A,M 

A 



.WRCHAR first 
call to WRCHAR 
with 57 (~"W") 

.BOOS 

Cail to BDOS 
Function # 2, 
Character "W" 

(SID code to 
intercept call) 
= first character 
.WRMSG now we're 
back to our 
program, with 
another CALL. 



S=015'4 P=011B LXI H,012A -.WALLAMSG 
S=0154 P=011E CALL 010C .WRMSG 



M .WALLAMSG 



B=0000 D=0200 H=012A S=0152 P=010C MOV A. 
8=0000 D=0200 H=012A S=0152 P=0100 ORA A 
B=0000 0=0200 H=012A S=0152 P=010E RZ 
8=0000 D=0200 H=012A S=0152 P=010F CALL 0106 .WRCHAR 

B=0000 0=0200 H=012A S=0150 P=0106 MVI C 
B=0002 D=0200 H=012A S=0150 P=0108 MOV E 



02 
A 



abort with "return" 



♦0109 
#G, .WRMSG 
W 

*010C .WRMSG 
#TW100 

-Z-E- 

-Z-E- 

-Z-E- 

-Z-E- 

-Z-E- 
STOP: 

-Z-E- 
REBOOT: 

-Z-E- A 
*7A03 



GO, skip traces 
Should be ALL A 



what happened? 



A=00 
A=00 
A=00 
A=00 
A=00 

A=00 

^00 



Trace without call: 
8=0000 0=0200 H=7938 
B=0000 0=0200 H=793B 
8=0000 D=0200 H=793B 
B=0000 D=0200 H=793B S=0154 
B=0000 0=0200 H=0130 S=0154 



=0152 
=0152 
=0152 



M 



H.0130 .WASHMSG 
010C .WRMSGW 



P=010C MOV 
P=0100 ORA 
P=010E RZ 
P=0121 LXI 
P=0124 CALL 

Called WRMSG, printed another "W" and stopped! 
B=0000 D=0200 H=793B S=0154 P=0127 JMP 0000 .REBOOT 

abort with "return" so we can restart. 
B=0000 0=0200 H=793B S=0154 P=0000 JMP 7A03 

It appears that the WRMSG subroutine is not saving the HL 
register pair, nor is HL being incremented on each loop. 
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#A10F 

010F JMP 200 We'll put a "hot patch" at the end of the WRUSQ 

0112 subroutine to save the HL pair, call the WRCHAR 

#A200 subroutine, restore the HL pair, then increment HL. 

0200 PUSH H We're not using the region above 200, so place patch 

0201 CALL .WRCHAR in this region. 

0204 POP H 

0205 INX H 

0206 JMP .WRMSG 
0209 

*G100, .WRMSG Ok, now restart the program and stop at the first call 
to WRMSG. 

*010C .WRMSG Here we are. HL addresses the message to print, which 
#D is the default display address following a breakpoint: 

012A: 57 41 4C 4C 41 20 WALLA = message to print. 

0130: 57 41 53 48 56 45 52 53 20 31 2E 34 24 31 00 02 WASHVERS 1.451.. 

#TW100 Trace without calls: shows only the activity in WRMSG. 

AO0 B=0000 D=0000 H=012A S=0152 P=010C MOV A,M .WALLAMSG 

A=57 B»0000 0=0000 H-012A S=0152 P=010D OR A A first character 

A=57 B=0000 0=0000 H=012A S=0152 P=010E RZ is -57 = "W" 

A=57 BO000 D=0000 H=012A S=0152 P=010F JMP 0200 N° w in P a ^h 

A=57 B=0000 D=0000 H=012A S=0152 P=0200 PUSH H area - 

A=57 8=0000 0=0000 H=012A S=0150 P=0201 CALL 0106 .WRCHARW = character 

-Z-E- A=00 8=0000 0=0200 H=793B S=0150 P=0204 POP H 

-Z-E- A=00 B=0000 0=0200 H=012A S=0152 PO205 INX H Mov e to next 

-Z-E- A=00 B=0000 D=0200 H=012B S=0152 P=0206 JMP 010C .WRMSG character 

WRMSG: Looping back. 

-Z-E- A=00 8=0000 0=0200 H=012B S=0152 P=010C MOV A,M 
-Z-E- A=41 B=0000 D=0200 H=0128 S=0152 P=010D 0RA A 
... E- A=41 B=0000 0=0200 H=012B S=0152 P=010E RZ 
— E- A=41B=0000 D=0200 H=012B S=0152 P=010F JMP 0200 
— E- A=41 B=0000 D=0200 H=012B S=0152 P=0200 PUSH H Here's the next 

... E- A=41 8=0000 D=0200 H=012B S=0150 P=0201 CALL 0106 .WRCHARA character 
-Z-E- A=00 8=0000 0=0200 H=793B S=0150 P=0204 POP H ( = " A ") 
-Z-E- A=00 B=0000 0=0200 H=012B S=0152 P=0205 INX H 
-Z-E- A=00 B=0000 0=0200 H=012C S=0152 P=0206 JMP 010C .WRMSG 

WRMSG: 

-Z-E- A=00 B=0000 D=0200 H=012C S=0152 P=010C MOV A,M 
*010D Abort with "return" 

#P.ST0P Set a permanent break at STOP, then GO from 

#G100 toe beginning of the program: 

WALLA WASHVERS 1.4S1WALLA WASHVERS 1 .4S1WASHVERS 1.4$1 

01 PASS 0127 .STOP Things ioofc better, but "00" byte missing on messages. 

-Z-E- A=00 B=0000 D=0200 H=013E S=0154 P=0127 JMP 0000 .REBOOT 
♦0000 .REBOOT 

#S.WALLAMSG+4 Piace a 00 byte at the end of each message. 
012E 41 (leave this value, 41 = "A" in WALLA) 
012F 20 (changed to 00 from blank) 
0130 57 . 

#S.WASHMSG+4 Place 00 byte at the end of the second message. 

0134 56 

0135 45 . 

#G100 Break at STOP remains set, GO from the beginning. 

WALLAWALLAWASH Looks good, we now have enough information to 

01 PASS 0127 .STOP go back and change the source program using ED. 

-Z-E- A=00 B=0000 D=0200 H=0134 S=0154 P=0127 JMP 0000 .REBOOT 
*0000 .REBOOT 
#G0 
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